ruvnet-brain 4.7.19 → 4.7.21

package/plugin/scripts/update-apply.mjs

@@ -83,23 +83,169 @@ function receipt(event, data) {
   try { fs.appendFileSync(RECEIPTS, JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + '\n'); } catch { /* ledger must not break the engine */ }
 }
 
-// ── the lock (finding 5): atomic mkdir; stale-pid reclaim (issue-fix.mjs house pattern) ──────────
-function acquireLock(target) {
+// ── the lock (finding 5): atomic mkdir; the owner is judged by PROCESS IDENTITY, not pid alone ────
+// 4.7.21 (audit C-opus, reproduced): a pid-only check let any unrelated process that reused the pid hold
+// the spine forever, and an empty owner.json (the window between mkdir and the owner write) was deleted out
+// from under a live writer. The owner now records its process start time; a live pid whose start differs is
+// a reused pid. A lock held by a genuinely live owner is BUSY (exit 75), never success: host convergence
+// must not read "nothing applied" as "applied".
+export const BUSY_EXIT = 75; // EX_TEMPFAIL
+const OWNER_PUBLISH_GRACE_MS = 60_000;
+function processStartOf(pid) {
+  try {
+    const r = process.platform === 'win32'
+      ? spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+        `(Get-Process -Id ${Number(pid)} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`], { encoding: 'utf8' })
+      : spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' } });
+    return r.status === 0 ? String(r.stdout || '').trim() || null : null;
+  } catch { return null; }
+}
+const startMs = (text) => Date.parse(/T.*Z$/.test(text) ? text : `${text} UTC`);
+function lockOwnerState(owner) {
+  if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid < 1) return 'incomplete';
+  try { process.kill(owner.pid, 0); } catch (error) { if (error?.code !== 'EPERM') return 'stale'; }
+  const observed = processStartOf(owner.pid);
+  if (!observed) return 'live'; // alive and unprovable: never steal it
+  if (owner.processStart) return observed === owner.processStart ? 'live' : 'stale';
+  // A pre-4.7.21 owner has only startedAt. Its process existed when it wrote that, so a process that
+  // started later (lstart has 1 s resolution) is a different process holding a reused pid.
+  const written = Date.parse(owner.startedAt || '');
+  return Number.isFinite(written) && startMs(observed) > written + 2000 ? 'stale' : 'live';
+}
+function lockAgeMs() {
+  let newest = 0;
+  for (const p of [LOCK, path.join(LOCK, 'owner.json')]) { try { newest = Math.max(newest, fs.lstatSync(p).mtimeMs); } catch { /* absent */ } }
+  return Date.now() - newest;
+}
+// 4.7.21 review (Codex #1, the quarantine path): judging an owner and then moving LOCK aside are two steps, so a
+// contender could move a lock that had changed since it was judged. Moving it back on a mismatch left a window in which
+// a third run's fresh lock blocked the restore; and an owner-less lock (raw null) was indistinguishable from another
+// run's directory between its mkdir and its owner write, so the restore never ran and both runs applied. A takeover now
+// holds an exclusive claim file inside the judged directory and re-checks it (dev/ino + owner bytes) before moving it;
+// a run releases only the lock that carries its own token.
+// Round 4 (Codex #1): mkdir-then-publish left an owner-less moment; a run paused there past the grace was judged debris,
+// claimed, re-checked (still owner-less: "the same") and moved aside with the owner it published meanwhile: two runs
+// applied. LOCK is now built complete in a staging sibling and published by ONE rename, so it never exists without its
+// owner; a rename onto an existing lock fails (ENOTEMPTY/EEXIST, EPERM/EACCES on Windows) and that lock is judged.
+const CLAIM_STALE_MS = 5 * 60_000;
+const CLAIM_FILE = /^takeover(?:-(\d+))?\.json$/;
+function observeLock() {
+  const stat = fs.lstatSync(LOCK, { bigint: true });
+  if (!stat.isDirectory()) throw Object.assign(new Error('the update lock is not a directory'), { code: 'ENOTDIR' });
+  let raw = null;
+  try { raw = fs.readFileSync(path.join(LOCK, 'owner.json'), 'utf8'); } catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  return { identity: `${stat.dev}:${stat.ino}`, raw };
+}
+const readRaw = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
+// A claim file must not restart the publication grace (Opus r2 #6): writing or removing one bumps LOCK's mtime, which
+// lockAgeMs reads, so LOCK's own times are put back.
+function keepLockTimes(change) {
+  let before = null;
+  try { before = fs.lstatSync(LOCK); } catch { /* judged below */ }
+  try { return change(); } finally { if (before) try { fs.lutimesSync(LOCK, before.atime, before.mtime); } catch { /* gone */ } }
+}
+const GONE = Symbol('judged lock vanished');
+function claimTakeover() {
+  let highest = -1; let highestName = null; let names;
+  // The judged lock vanished (another run moved it): re-judge rather than throw out of main (Fable r2 P3-1).
+  try { names = fs.readdirSync(LOCK); } catch (error) { if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return GONE; throw error; }
+  for (const name of names) {
+    const match = CLAIM_FILE.exec(name);
+    const level = match ? (match[1] ? Number(match[1]) : 0) : -1;
+    if (level > highest) { highest = level; highestName = name; }
+  }
+  if (highestName) {
+    let ageMs = 0;
+    try { ageMs = Date.now() - fs.lstatSync(path.join(LOCK, highestName)).mtimeMs; } catch { return null; }
+    if (!(ageMs > CLAIM_STALE_MS)) return null; // another run is mid-takeover
+  }
+  const level = highest + 1;
+  const file = path.join(LOCK, level ? `takeover-${level}.json` : 'takeover.json');
+  const token = crypto.randomBytes(16).toString('hex');
+  try { keepLockTimes(() => fs.writeFileSync(file, JSON.stringify({ token, pid: process.pid, claimedAt: new Date().toISOString() }), { flag: 'wx' })); }
+  catch (error) { if (error?.code === 'EEXIST') return null; if (error?.code === 'ENOENT') return GONE; throw error; }
+  return { file, token };
+}
+const dropClaim = (claim) => { try { if (readRaw(claim.file)?.includes(claim.token)) keepLockTimes(() => fs.unlinkSync(claim.file)); } catch { /* gone with its directory */ } };
+function removeObservedLock(observed) {
+  const claim = claimTakeover();
+  if (claim === GONE) return 'changed';
+  if (!claim) return 'busy';
+  let same = false;
+  try {
+    const now = observeLock();
+    same = now.identity === observed.identity && now.raw === observed.raw && Boolean(readRaw(claim.file)?.includes(claim.token));
+  } catch { same = false; }
+  if (!same) { dropClaim(claim); return 'changed'; }
+  const quarantine = `${LOCK}.stale-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try { fs.renameSync(LOCK, quarantine); } catch (error) { if (error?.code === 'ENOENT') return 'changed'; dropClaim(claim); throw error; }
+  if (!readRaw(path.join(quarantine, path.basename(claim.file)))?.includes(claim.token)) {
+    try { if (!fs.existsSync(LOCK)) fs.renameSync(quarantine, LOCK); } catch { /* keep as evidence */ }
+    return 'changed';
+  }
+  try { fs.rmSync(quarantine, { recursive: true, force: true }); } catch { /* best effort */ }
+  return 'removed';
+}
+/** LOCK appears with its owner already inside, by one rename that fails when a populated lock is there. */
+const CONTENDED = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES']);
+function publishLock(content) {
+  const staged = `${LOCK}.acquire-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  const dropStaged = () => { try { fs.rmSync(staged, { recursive: true, force: true }); } catch { /* best effort */ } };
+  try {
+    fs.mkdirSync(staged);
+    fs.writeFileSync(path.join(staged, 'owner.json'), content, { flag: 'wx' });
+  } catch (error) { dropStaged(); throw error; } // staging failures are real errors, never contention
+  try { fs.renameSync(staged, LOCK); } catch (error) {
+    dropStaged();
+    // A refused publication is contention even if LOCK is gone a moment later: its holder can release in between, and
+    // re-checking existsSync here rethrew a raw ENOTEMPTY (exit 1, not BUSY_EXIT) (Opus r3 P2-1). The caller re-observes
+    // and tries again when the lock has vanished, as kb/refresh-run.mjs does.
+    if (CONTENDED.has(error?.code)) throw Object.assign(new Error('the update lock is held'), { code: 'EEXIST' });
+    throw error;
+  }
+}
+export function acquireLock(target) {
   fs.mkdirSync(BRAIN_HOME, { recursive: true });
-  for (let attempt = 0; attempt < 2; attempt++) {
+  const processStart = processStartOf(process.pid);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const token = crypto.randomBytes(16).toString('hex');
     try {
-      fs.mkdirSync(LOCK); // atomic: exists → EEXIST
-      writeAtomic(path.join(LOCK, 'owner.json'), JSON.stringify({ pid: process.pid, host: os.hostname(), target, startedAt: new Date().toISOString() }));
-      return true;
-    } catch {
-      const owner = readJSON(path.join(LOCK, 'owner.json'));
-      try { if (owner && owner.pid) { process.kill(owner.pid, 0); return false; } } catch { /* stale */ }
-      try { fs.rmSync(LOCK, { recursive: true, force: true }); } catch { /* race — retry once */ }
+      publishLock(JSON.stringify({ pid: process.pid, host: os.hostname(), target, token,
+        processStart, startedAt: new Date().toISOString() }));
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      let observed;
+      try { observed = observeLock(); } catch (observeError) { if (observeError?.code === 'ENOENT') continue; throw observeError; }
+      let owner = null;
+      try { owner = observed.raw === null ? null : JSON.parse(observed.raw); } catch { /* incomplete */ }
+      const state = lockOwnerState(owner);
+      if (state === 'live') return { acquired: false, owner };
+      if (state === 'incomplete' && lockAgeMs() < OWNER_PUBLISH_GRACE_MS) return { acquired: false, owner: null };
+      const outcome = removeObservedLock(observed);
+      if (outcome === 'busy') return { acquired: false, owner: null };
+      if (outcome === 'removed') {
+        receipt('StaleLockReclaimed', { owner: owner ? { pid: owner.pid, host: owner.host, startedAt: owner.startedAt } : null, state });
+      }
+      continue; // 'changed': judge the directory that is there now
     }
+    return { acquired: true, token };
   }
-  return false;
+  return { acquired: false, owner: null };
+}
+/** Releases LOCK only while it still carries this run's token: never another run's lock. */
+export function releaseLock(lock) {
+  if (!lock?.acquired || !lock.token) return false;
+  if (!readRaw(path.join(LOCK, 'owner.json'))?.includes(`"token":"${lock.token}"`)) return false;
+  const released = `${LOCK}.released-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try { fs.renameSync(LOCK, released); } catch { return false; }
+  const moved = readRaw(path.join(released, 'owner.json'));
+  if (!moved?.includes(`"token":"${lock.token}"`)) {
+    try { if (!fs.existsSync(LOCK)) fs.renameSync(released, LOCK); } catch { /* keep as evidence */ }
+    return false;
+  }
+  try { fs.rmSync(released, { recursive: true, force: true }); } catch { /* gone */ }
+  return true;
 }
-function releaseLock() { try { fs.rmSync(LOCK, { recursive: true, force: true }); } catch { /* gone */ } }
 
 // ── crash recovery (finding 21): resolve any incomplete transaction BEFORE new work ─────────────
 function recoverTxn() {
@@ -377,7 +523,11 @@ function main() {
     return 0;
   }
 
-  if (!acquireLock(argv.join(' '))) { console.log('another update is in progress — exiting (concurrency 1).'); return 0; }
+  const lock = acquireLock(argv.join(' '));
+  if (!lock.acquired) {
+    console.log(`another update is in progress${lock.owner?.pid ? ` (pid ${lock.owner.pid})` : ''} — nothing was applied; exiting busy (${BUSY_EXIT}, concurrency 1).`);
+    return BUSY_EXIT;
+  }
   try {
     recoverTxn();
 
@@ -456,9 +606,30 @@ function main() {
     receipt('UpdateChecked', { active: active?.version ?? null, staged: stagedVersion });
     return applyFromDir(staged.dir, stagedVersion, active ? 'auto-update' : 'auto-seed') ? 0 : 1;
   } finally {
-    releaseLock();
+    releaseLock(lock);
     if (has('--gc') || !has('--no-gc')) { try { gc(); } catch { /* GC never fails the run */ } }
   }
 }
 
-if (process.env.RUVNET_BRAIN_IMPORT_ONLY !== 'update-shell-test') process.exit(main());
+// #420 item 6: `--help` used to fall through to the default action (take the update lock and apply). Usage is derived from
+// the flags main() reads; help and unknown flags answer BEFORE main() so they touch no state (no BRAIN_HOME mkdir, lock, network).
+const USAGE = [
+  'usage: node update-apply.mjs [--auto [--expected-version <v>] | --seed | --from-dir <path> | --rollback | --dev [pluginDir] | --dev-off | --doctor] [--gc | --no-gc]',
+  '  (no flag = --auto: newest host-staged plugin version, applied only if newer than active)',
+  '  --auto [--expected-version <v>]  unattended: apply the host-staged payload, optionally pinned to exactly <v>',
+  '  --seed                           seed the spine from the running plugin install',
+  '  --from-dir <path>                apply a specific plugin payload dir',
+  '  --rollback                       flip back to the previous generation',
+  '  --dev [pluginDir]                dev mode: point codeRoot at a checkout\'s plugin/',
+  '  --dev-off                        leave dev mode',
+  '  --doctor                         report spine state (read-only)',
+  '  --gc / --no-gc                   force / skip collecting unreferenced generations after the run',
+  '  --help, -h                       print this usage and exit without touching any state',
+].join('\n');
+const KNOWN_FLAGS = new Set(['--auto', '--seed', '--from-dir', '--rollback', '--dev', '--dev-off', '--doctor', '--gc', '--no-gc', '--expected-version']);
+if (process.env.RUVNET_BRAIN_IMPORT_ONLY !== 'update-shell-test') {
+  if (has('--help') || has('-h')) { console.log(USAGE); process.exit(0); }
+  const unknown = argv.filter((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+  if (unknown.length) { console.error(`✗ unknown argument: ${unknown.join(' ')}\n${USAGE}`); process.exit(2); }
+  process.exit(main());
+}

package/plugin/skills/release-proof/scripts/release-proof.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { isDirectInvocation } from '../../../scripts/entrypoint.mjs';
 
 export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe', 'release-qe'];
 
@@ -323,4 +324,4 @@ export function main(args = process.argv.slice(2)) {
   }
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/plugin/skills/ruvnet-brain/PLAYBOOK.md

@@ -41,8 +41,8 @@ went by (web searches, throwaway installs, scratch builds) before a single tool
 So, before the DO FIRST list and before beat 1:
 
 - **Say the one capability that would materially help, in ONE sentence, within ~2 minutes** —
-  *"Consider `<capability>` — `<concrete benefit for THIS task>`. Say 'use `<capability>`' and I'll
-  wire it, or ignore this."* Then carry straight on. If nothing genuinely fits, **say nothing about
+  *"`<capability>` fits here — `<concrete benefit for THIS task>`; 'use `<capability>`' wires it."*
+  A statement, never a question or approval dialog. Then carry straight on. If nothing genuinely fits, **say nothing about
   tooling at all**; silence is the correct and common answer, and a forced tie-in is worse than none.
 - **Budget: at most THREE `search_ruvnet` calls to get there.** Enough to confirm the capability
   exists and what it is called — not enough to design the integration, and not meant to be.

package/plugin/skills/ruvnet-brain/SKILL.md

@@ -23,8 +23,9 @@ missing. A colleague who knows the right tool and tells you twenty minutes in di
 So, on any build/plan/fix request, in this order:
 
 1. **Within ~2 minutes, say the one thing that would help — or say nothing.** One or two sentences:
-   *"Consider `<capability>` — `<the concrete benefit for THIS task>`. Say 'use `<capability>`' and
-   I'll wire it, or ignore this and I'll carry on."* Then get straight on with the actual work. If
+   *"`<capability>` fits here — `<the concrete benefit for THIS task>`; 'use `<capability>`' wires it."*
+   It is a statement, not a question: never open a question or approval dialog for an optional
+   recommendation, and it authorizes no install. Then get straight on with the actual work. If
    nothing genuinely fits, say nothing at all about tooling — silence is the correct and common
    answer, and a forced tie-in is worse than no recommendation (rule 4 below).
 2. **At most THREE `search_ruvnet` calls before that first recommendation.** Three is enough to

package/scripts/adr-072-completion.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { verifyCapabilityClaimAggregate } from '../plugin/scripts/capability-claim-evidence.mjs';
 import { LEGACY_REVIEW_MODEL_IDS } from './review-model-defaults.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REQUIRED_REVIEWERS = LEGACY_REVIEW_MODEL_IDS;
@@ -91,7 +92,7 @@ export function evaluateCompletion({ root = ROOT, run = command,
   return { ok: failures.length === 0, head, version, receiptFile, failures };
 }
 
-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)) {
   const receiptIndex = process.argv.indexOf('--receipt');
   const result = evaluateCompletion({ receiptFile: receiptIndex >= 0 ? path.resolve(process.argv[receiptIndex + 1]) : undefined });
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/agentdb-context.mjs

@@ -39,6 +39,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 HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '..');
@@ -210,7 +211,7 @@ function main() {
 }
 
 function isMain() {
-  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 }
 if (isMain()) process.exit(main());

package/scripts/agentdb-fleet-doctor.mjs

@@ -67,9 +67,25 @@ async function doctor(proj) {
     let gitlog = '';
     try { gitlog = execFileSync('git', ['-C', proj, 'log', '--oneline', '-8'], { encoding: 'utf8', timeout: 10000 }).trim(); } catch { /* not a repo */ }
     const val = `SEEDED CHECKPOINT ${new Date().toISOString()} (agentdb-fleet-doctor — no canonical checkpoint existed; the session-start hook had nothing to surface). Recent git history:\n${gitlog || '(not a git repo)'}\nMaintain from now on: append a NEW project-state-current-<epochms> row after meaningful work; never overwrite.`;
+    const seedKey = `project-state-current-${Date.now()}`;
     fs.copyFileSync(db, `${db}.bak-fleet-doctor-${Date.now()}`);
-    const r = ruflo(proj, ['memory', 'store', '-k', `project-state-current-${Date.now()}`, '--value', val, '-n', name]);
-    row.seeded = r.status === 0 && /stored successfully/i.test(r.out);
+    const r = ruflo(proj, ['memory', 'store', '-k', seedKey, '--value', val, '-n', name]);
+    // ADR-063 / 2026-08-13 incident: `ruflo memory store`'s own "[OK] ... stored successfully"
+    // wording is not evidence of a write — that exact line was on stdout throughout the incident
+    // that left three days of memory unrecoverable. The only accepted proof is retrieving the SAME
+    // key back through the managed interface and reading the VALUE (degradation-watch.mjs's
+    // proveMemoryDurable() / record-lesson.mjs precedent). The FIX-2 canary below round-trips a
+    // DIFFERENT key later in this function — it proves the namespace is writable in general, not
+    // that THIS seeded checkpoint's write specifically persisted.
+    row.seeded = false;
+    if (r.status === 0) {
+      const back = ruflo(proj, ['memory', 'retrieve', '-k', seedKey, '-n', name, '--value-only']);
+      // A 60-char PREFIX match, not the full multi-line value: `val` embeds `gitlog`, and this file's
+      // own FIX-2 canary check (below) already establishes that this CLI's output can truncate/reflow
+      // multi-line content in ways a full-string match would false-negative on. The prefix carries the
+      // per-write ISO timestamp, so it still identifies THIS write, not a stale or unrelated one.
+      row.seeded = back.status === 0 && back.out.includes(val.slice(0, 60));
+    }
     row.checkpoint = row.seeded;
   }
 
@@ -79,16 +95,22 @@ async function doctor(proj) {
     row.episodes = Number(sql(db, 'SELECT count(*) FROM episodes;') ?? 0);
   }
 
-  // VERIFY: real round-trip through the real CLI in the project's own namespace.
+  // VERIFY: real round-trip through the real CLI in the project's own namespace — EXACT KEY, never
+  // a semantic `memory search` match. The prior check matched a generic substring every canary this
+  // project has EVER written shares ("fleet-doctor-cana…" / "round-trip canary"), not THIS run's
+  // unique key/value, so a stale canary from a PRIOR run still ranked by `memory search` made a run
+  // whose CURRENT write silently failed report `roundtrip: true` anyway — the same "claimed success
+  // is not evidence of a write" gap already fixed this way in `record-lesson.mjs`, `distill-
+  // project.mjs`, and `health-repair.mjs`'s fleet receipt, and the exact discipline `ground-
+  // ruvnet.sh` already documents for every other write in this repo: "never infer a broken write
+  // from... semantic-search misses... unique-key store -> exact-key retrieve and read the returned
+  // VALUE."
   const canaryKey = `fleet-doctor-canary-${Date.now()}`;
   const canaryVal = `round-trip canary ${new Date().toISOString()}`;
   const stored = ruflo(proj, ['memory', 'store', '-k', canaryKey, '--value', canaryVal, '-n', name]);
   if (stored.status === 0) {
-    const found = ruflo(proj, ['memory', 'search', '-q', 'fleet-doctor round-trip canary', '-n', name, '--limit', '3']);
-    // The result table TRUNCATES keys (`fleet-doctor-cana...`) — asserting on the full key was a
-    // false-negative bug (caught on first run, 2026-07-13, SpotOn: store fine, MY check wrong —
-    // the exact lesson-agentdb-was-never-broken defect class). Match what the table can show.
-    row.roundtrip = found.out.includes('fleet-doctor-cana') || found.out.includes('round-trip canary');
+    const found = ruflo(proj, ['memory', 'retrieve', '-k', canaryKey, '-n', name, '--value-only']);
+    row.roundtrip = found.status === 0 && found.out.trim() === canaryVal;
   }
   return row;
 }

package/scripts/approved-runtime.mjs

@@ -48,6 +48,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { retryTransientResult } from './transient-gh.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const APPROVED_RUNTIME_KIND = 'ruvnet-brain-approved-runtime';
@@ -417,6 +418,6 @@ async function main() {
   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; });
 }

package/scripts/architecture-review-lock.mjs

@@ -3,6 +3,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { REPO_ROOT, evaluateDoc, blockingFindings } from './doc-currency.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const GOVERNING_ADR = 'docs/adr/0103-routing-architecture-review-lock.md';
 
@@ -39,6 +40,6 @@ export function main(argv = process.argv.slice(2)) {
   return result.pass ? 0 : 1;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = main();
 }

package/scripts/ascii-drift.mjs

@@ -40,6 +40,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '..');
@@ -230,7 +231,7 @@ function main() {
 }
 
 function isMain() {
-  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 }
 if (isMain()) process.exit(main());

package/scripts/brain-latency-50.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -222,6 +223,6 @@ export async function main(argv = process.argv.slice(2)) {
   return summary.passed === summary.questions && summary.timedOut === 0 ? 0 : 1;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = await main();
 }

package/scripts/brain-novice-50.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { performance } from 'node:perf_hooks';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -182,21 +183,6 @@ async function main() {
   console.log(`REPORT ${output}`);
 }
 
-// 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)) {
   main().catch((error) => { console.error(error.stack || error.message); process.exitCode = 1; });
 }

package/scripts/brain-score.mjs

@@ -30,6 +30,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.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const DAY = 86_400_000;
@@ -203,12 +204,22 @@ export async function readCoverage(rootOverride) {
   };
 }
 
-/** A reading past its dimension's `maxAgeDays`, or with no timestamp at all, is not current. */
+/**
+ * A reading past its dimension's `maxAgeDays`, or with no timestamp at all, is not current.
+ *
+ * MEASURED 2026-10-16: a reading dated AFTER `now` (clock skew between the writer and this read, or
+ * a corrupt/hand-edited `recorded`/`generatedAt` stamp) produced a NEGATIVE `ageDays` — e.g. `-3` —
+ * which is less than any positive `maxAgeDays`, so `stale` came back `false` with `why: null`. A
+ * corrupted-into-the-future timestamp is exactly as untrustworthy as a corrupted-into-the-past one;
+ * this file's own stated purpose (see header, ISSUE #258) is that a reading nobody can vouch for is
+ * never silently used, and a future stamp was sailing through as BETTER than fresh.
+ */
 export function staleness(at, maxAgeDays, now = Date.now()) {
   if (!at) return { stale: true, ageDays: null, why: 'no timestamp recorded' };
   const ms = now - Date.parse(at);
   if (!Number.isFinite(ms)) return { stale: true, ageDays: null, why: 'unparseable timestamp' };
   const ageDays = Math.round((ms / DAY) * 10) / 10;
+  if (ageDays < 0) return { stale: true, ageDays, why: `${ageDays}d — recorded in the future (clock skew or corrupt timestamp)` };
   return { stale: ageDays > maxAgeDays, ageDays, why: ageDays > maxAgeDays ? `${ageDays}d > ${maxAgeDays}d budget` : null };
 }
 
@@ -250,7 +261,7 @@ export function composite(dims, kind) {
 }
 
 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/build-bundle.mjs

@@ -69,6 +69,7 @@ import { orgRepoCount } from './org-repo-count.mjs';
 import { assertCapabilityOnlyStore } from '../kb/capability-only.mjs';
 import { CURRENCY_BASIS, corpusCurrencyBlock } from './corpus-currency.mjs';
 import { loadFixture } from './oracle/repo-recall.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -1097,7 +1098,7 @@ node forge-ask.mjs --dir . --name ruvector --variant big --q "what is the RVF co
 }
 
 // ---- CLI -----------------------------------------------------------------------------------------
-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)) {
   const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   // Corpus content is a release asset, not a Git blob. A clean worktree has zero stores unless the
   // operator supplies the canonical external corpus directory (or has already built one into kb/,

package/scripts/build-concepts.mjs

@@ -22,6 +22,7 @@ import { fileURLToPath } from 'node:url';
 import { observeSourceUniverse } from './source-coverage.mjs';
 import { materializePublicInputs } from './public-inputs.mjs';
 import { buildConceptAggregate } from './corpus-aggregates.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
@@ -44,7 +45,7 @@ export async function main() {
   }
 }
 
-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().catch((error) => {
     console.error(`[build-concepts] ${error.message}`);
     process.exitCode = 1;

package/scripts/candidate-ci-receipt.mjs

@@ -5,6 +5,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { verifyPayloadMembers } from './release-payload.mjs';
 import { validateQualificationReceipt } from './release-qualification.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const REQUIRED_CI_JOBS = ['candidate-preflight', 'release-acceptance-linux',
   'release-acceptance-windows', 'release-acceptance-macos', 'release-qe'];
@@ -50,7 +51,7 @@ export function createCandidateCiReceipt({ sha, runId, runAttempt, results, ciRe
     verdict: 'PASS', skipped: 0, unknown: 0 };
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const receipt = createCandidateCiReceipt({ sha: process.env.CANDIDATE_SHA,
     runId: Number(process.env.GITHUB_RUN_ID), runAttempt: Number(process.env.GITHUB_RUN_ATTEMPT),
     ciResult: process.env.CI_RESULT,

package/scripts/candidate-host-evidence.mjs

@@ -6,6 +6,7 @@ import { stagedHostVerifier, readCandidateRetrieval, verifyCandidateRetrievalAss
 import { payloadIdFor } from './release-payload.mjs';
 import { validateRetrievalCanaryReceipt } from './retrieval-canary.mjs';
 import { HOST_WARMUP_TIMEOUT_MS, RELEASE_SEARCH_DEADLINE_MS } from './host-install-matrix.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const arg = (name) => {
   const index = process.argv.indexOf(name);
@@ -93,7 +94,7 @@ export async function buildCandidateHostEvidence({ manifestFile, packagePath, bu
   };
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const evidence = await buildCandidateHostEvidence({ manifestFile: arg('--manifest'),
     packagePath: arg('--package'), bundlePath: arg('--bundle'), planFile: arg('--plan'), coverageFile: arg('--coverage'), failureFile: arg('--out') ? `${arg('--out')}.failure.json` : null },
   { sequentialSearches: process.argv.includes('--sequential-searches') });

package/scripts/card-from-source.mjs

@@ -29,6 +29,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { storeRoot, darkStores } from '../kb/store-root.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
@@ -104,7 +105,7 @@ export function applyCardToFiles(files, card, name, insert = insertSorted) {
 }
 
 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/ci/warm-brain-models.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { requiredEmbedderModels } from '../../plugin/test/model-cache.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 async function main() {
   const modelCache = process.env.KB_MODEL_CACHE;
@@ -25,4 +26,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();