ruvnet-brain 4.7.20 → 4.7.21

package/kb/model-requirements.mjs

@@ -90,8 +90,11 @@ export function requiredEmbedderModels(kbDir) {
   return models.size ? [...models].sort() : [MINILM_MODEL];
 }
 
+// A model is present only when the files the strict offline reader loads are there (#301): a
+// folder left by a download that did not finish (no onnx/model_quantized.onnx) counts as missing,
+// or the doctor calls a cache warm that cannot answer a query.
 export function missingEmbedderModels(modelCache, models) {
-  return models.filter((model) => !fs.existsSync(modelPath(modelCache, model)));
+  return models.filter((model) => !modelCacheReady(modelCache, model));
 }
 
 export function configureTransformersModel(T, modelCache, model) {

package/kb/refresh-run.mjs

@@ -58,15 +58,19 @@ function sameExecutable(left, right) {
   try { return fs.realpathSync(left) === fs.realpathSync(right); } catch { return path.resolve(left || '') === path.resolve(right || ''); }
 }
 
-function ownerState(owner, { hostname, inspectProcess, isAlive }) {
-  if (!owner || owner.host !== hostname || !owner.processStart || !owner.executable) return 'unknown';
-  const observed = inspectProcess
+function observeOwnerProcess(owner, { inspectProcess, isAlive }) {
+  return inspectProcess
     ? inspectProcess(owner.pid)
     : (isAlive && isAlive !== alive)
         ? (isAlive(owner.pid)
             ? { state: 'live', processStart: owner.processStart, executable: owner.executable }
             : { state: 'dead' })
         : observedProcessIdentity(owner.pid);
+}
+
+function ownerState(owner, { hostname, inspectProcess, isAlive }) {
+  if (!owner || owner.host !== hostname || !owner.processStart || !owner.executable) return 'unknown';
+  const observed = observeOwnerProcess(owner, { inspectProcess, isAlive });
   if (observed?.state !== 'live') return observed?.state === 'dead' ? 'dead' : 'unknown';
   return observed.processStart === owner.processStart && sameExecutable(observed.executable, owner.executable)
     ? 'live'
@@ -78,6 +82,135 @@ export function inspectRefreshOwner(owner, { hostname = os.hostname(), inspectPr
   return ownerState(owner, { hostname, inspectProcess, isAlive });
 }
 
+// A lock nobody can prove alive must not wedge every later run (4.7.21, audit C). Liveness cannot be proven
+// across hosts (and on macOS os.hostname() follows the network, so "another host" is often this Mac on
+// another Wi-Fi: ownerVerdict checks the pid here first), but a refresh run cannot outlive the updater's own deadlines. An owner.json that cannot be
+// read or lacks its identity is debris once no writer could still be publishing it.
+export const REMOTE_OWNER_DEAD_MS = 3 * 3600_000;
+export const INCOMPLETE_OWNER_RECLAIM_MS = 3600_000;
+const ownerComplete = (owner) => owner?.schemaVersion === 3 && Boolean(owner.runId && owner.token && owner.host
+  && Number.isSafeInteger(owner.pid) && owner.receiptPath && owner.brainHome);
+const removalCommand = (lockPath) => (process.platform === 'win32'
+  ? `Remove-Item -Recurse -Force "${lockPath}"` : `rm -rf "${lockPath}"`);
+function newestMtimeMs(...files) {
+  let newest = Number.NaN;
+  for (const file of files) {
+    try { const ms = fs.lstatSync(file).mtimeMs; if (!(newest >= ms)) newest = ms; } catch { /* absent */ }
+  }
+  return newest;
+}
+
+/**
+ * 'dead' also for a remote owner past REMOTE_OWNER_DEAD_MS; every other answer is ownerState's.
+ * 4.7.21 review (Opus updater #2, reproduced): on macOS the hostname follows the network, so an owner recorded
+ * under "another host" is often THIS Mac, asleep mid-update on the old Wi-Fi. Its pid is inspected here first: the
+ * same pid alive with the same process start and executable IS the owner, whatever the hostname says. Only an
+ * absent or different local process may be aged out.
+ */
+function ownerVerdict(owner, { hostname, inspectProcess, isAlive, nowMs }) {
+  const state = ownerState(owner, { hostname, inspectProcess, isAlive });
+  if (state !== 'unknown' || !ownerComplete(owner) || owner.host === hostname) return { state, reason: 'exact-dead-owner' };
+  if (owner.processStart && owner.executable) {
+    const local = observeOwnerProcess(owner, { inspectProcess, isAlive });
+    if (local?.state === 'live' && local.processStart === owner.processStart
+      && sameExecutable(local.executable, owner.executable)) return { state: 'live', reason: 'same-process-other-hostname' };
+  }
+  const startedMs = Date.parse(owner.startedAt || '');
+  return Number.isFinite(startedMs) && nowMs - startedMs > REMOTE_OWNER_DEAD_MS
+    ? { state: 'dead', reason: 'stale-remote-owner' }
+    : { state, reason: null };
+}
+
+// ── takeover is serialized (4.7.21 review, Codex #1) ─────────────────────────────────────────────
+// Two contenders can judge the same abandoned lock. Without a claim, A reclaims and acquires, then B removes
+// A's FRESH lock on its stale judgement and both run. A takeover now (1) creates an exclusive claim file
+// inside the judged lock directory ('wx': one winner per directory instance), (2) re-checks, while holding
+// the claim, that the directory is the same one (dev/ino) and owner.json is byte-identical to what was
+// judged, and only then (3) moves it aside. A claim left by a crashed reclaimer is superseded by the next
+// numbered claim once CLAIM_STALE_MS old, so a crash mid-takeover cannot wedge the lock either.
+export const CLAIM_STALE_MS = 5 * 60_000;
+const CLAIM_FILE = /^takeover(?:-(\d+))?\.json$/;
+function dirIdentity(dir) {
+  const stat = fs.lstatSync(dir, { bigint: true });
+  if (!stat.isDirectory()) throw Object.assign(new Error(`${dir} is not a lock directory`), { code: 'ENOTDIR' });
+  return `${stat.dev}:${stat.ino}`;
+}
+function readRaw(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+// A claim file must not restart the age an incomplete owner is judged by (Opus r2 #6): writing or removing one bumps
+// the lock directory's mtime, which newestMtimeMs reads, so the directory's own times are put back.
+function keepDirectoryTimes(dir, change) {
+  let before = null;
+  try { before = fs.lstatSync(dir); } catch { /* judged below */ }
+  try { return change(); } finally { if (before) try { fs.lutimesSync(dir, before.atime, before.mtime); } catch { /* gone */ } }
+}
+const GONE = Symbol('judged lock vanished');
+function claimTakeover(lockPath, hostname) {
+  let highest = -1;
+  let highestName = null;
+  let names;
+  // The judged lock vanished (another reclaimer moved it): re-judge rather than throw (Fable r2 P3-1).
+  try { names = fs.readdirSync(lockPath); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return GONE; throw error; }
+  for (const name of names) {
+    const match = CLAIM_FILE.exec(name);
+    if (!match) continue;
+    const level = match[1] ? Number(match[1]) : 0;
+    if (level > highest) { highest = level; highestName = name; }
+  }
+  if (highestName) {
+    let ageMs = 0;
+    try { ageMs = Date.now() - fs.lstatSync(path.join(lockPath, highestName)).mtimeMs; } catch { return null; }
+    if (!(ageMs > CLAIM_STALE_MS)) return null; // another reclaimer is mid-takeover
+  }
+  const level = highest + 1;
+  const file = path.join(lockPath, level ? `takeover-${level}.json` : 'takeover.json');
+  const claim = { schemaVersion: 1, token: crypto.randomBytes(24).toString('hex'), host: hostname,
+    pid: process.pid, claimedAt: new Date().toISOString(), file };
+  let fd;
+  try { fd = keepDirectoryTimes(lockPath, () => fs.openSync(file, 'wx', 0o600)); } catch (error) {
+    if (error?.code === 'EEXIST') return null;
+    if (error?.code === 'ENOENT') return GONE;
+    throw error;
+  }
+  try { fs.writeFileSync(fd, `${JSON.stringify({ ...claim, file: undefined }, null, 2)}\n`); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  return claim;
+}
+function dropClaim(claim) {
+  try { if (readRaw(claim.file)?.includes(claim.token)) keepDirectoryTimes(path.dirname(claim.file), () => fs.unlinkSync(claim.file)); } catch { /* gone with its directory */ }
+}
+/**
+ * Remove the lock directory at `lockPath` only if it is still exactly the one observed. Returns 'removed',
+ * 'changed' (it is not the judged directory any more: re-judge it) or 'busy' (another reclaimer holds the claim).
+ */
+function removeObservedLock(lockPath, observed, { hostname, beforeRemove = null, afterClaim = null } = {}) {
+  const claim = claimTakeover(lockPath, hostname);
+  if (claim === GONE) return 'changed';
+  if (!claim) return 'busy';
+  afterClaim?.({ lockPath, claim });
+  let same = false;
+  try {
+    same = dirIdentity(lockPath) === observed.identity
+      && readRaw(path.join(lockPath, 'owner.json')) === observed.raw
+      && Boolean(readRaw(claim.file)?.includes(claim.token));
+  } catch { same = false; }
+  if (!same) { dropClaim(claim); return 'changed'; }
+  try { beforeRemove?.(claim); } catch (error) { dropClaim(claim); throw error; }
+  const tomb = `${lockPath}.stale-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  try { fs.renameSync(lockPath, tomb); } catch (error) {
+    if (error?.code === 'ENOENT') return 'changed';
+    dropClaim(claim);
+    throw error;
+  }
+  // Only the claim holder can move the judged directory, so the moved directory must carry this claim.
+  if (!readRaw(path.join(tomb, path.basename(claim.file)))?.includes(claim.token)) {
+    try { if (!fs.existsSync(lockPath)) fs.renameSync(tomb, lockPath); } catch { /* keep it as evidence */ }
+    throw new Error(`refresh lock takeover moved a directory it did not claim (${lockPath}); refusing`);
+  }
+  fs.rmSync(tomb, { recursive: true, force: true });
+  return 'removed';
+}
+
 /**
  * The ONE physical-path rule for brain directories. A user may reach the brain through a symlink
  * (`~/.cache -> /Volumes/<disk>`) while the updater knows it by its real path (Node resolves
@@ -103,15 +236,12 @@ export function refreshReceiptPath(brainHome, runId) {
   return file;
 }
 
-function abandonDeadOwner({ lockPath, owner, hostname, inspectProcess, isAlive, now }) {
-  const claimFile = path.join(lockPath, 'takeover.json');
-  const claim = { schemaVersion: 1, token: crypto.randomBytes(24).toString('hex'), host: hostname,
-    pid: process.pid, claimedAt: now() };
-  const fd = fs.openSync(claimFile, 'wx', 0o600);
-  try { fs.writeFileSync(fd, `${JSON.stringify(claim, null, 2)}\n`); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+/** Records the dead owner's run ABANDONED. Runs only while this process holds the takeover claim on its lock. */
+function abandonDeadOwner({ lockPath, owner, hostname, inspectProcess, isAlive, now, claim }) {
   const observed = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
+  const verdict = ownerVerdict(observed, { hostname, inspectProcess, isAlive, nowMs: Date.parse(now()) });
   if (observed.schemaVersion !== 3 || observed.runId !== owner.runId || observed.token !== owner.token
-    || ownerState(observed, { hostname, inspectProcess, isAlive }) !== 'dead') {
+    || verdict.state !== 'dead') {
     throw new Error('refresh owner changed or is no longer exactly dead during takeover');
   }
   const expectedReceipt = refreshReceiptPath(observed.brainHome, observed.runId);
@@ -136,7 +266,7 @@ function abandonDeadOwner({ lockPath, owner, hostname, inspectProcess, isAlive,
     receipt.status = 'ABANDONED';
     receipt.terminalVerdict = 'abandoned';
     receipt.finishedAt = now();
-    receipt.detail = { reason: 'exact-dead-owner', abandonedOwner: { host: observed.host, pid: observed.pid,
+    receipt.detail = { reason: verdict.reason, abandonedOwner: { host: observed.host, pid: observed.pid,
       processStart: observed.processStart, executable: observed.executable }, takeoverToken: claim.token };
     delete receipt.intendedStatus;
     delete receipt.intendedTerminalVerdict;
@@ -163,6 +293,7 @@ export function acquireRefreshLock({
   processStart = null,
   inspectProcess = null,
   afterStage = null,
+  afterTakeoverClaim = null,
 } = {}) {
   const root = path.resolve(kbDir || '');
   const lockPath = refreshLockPath(root);
@@ -204,23 +335,34 @@ export function acquireRefreshLock({
       // Windows refuses rename-over-existing with EPERM/EACCES rather than EEXIST. Treat those
       // codes as contention, then inspect the owner through the same liveness fence.
       if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error?.code)) throw error;
+      // Judge one exact directory: its identity and owner.json bytes are what the takeover re-checks later.
+      let observed;
+      try { observed = { identity: dirIdentity(lockPath), raw: readRaw(path.join(lockPath, 'owner.json')) }; }
+      catch (observeError) { if (['ENOENT', 'ENOTDIR'].includes(observeError?.code)) continue; throw observeError; }
       let owner = null;
-      try { owner = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8')); } catch {
-        throw new Error(`refresh lock owner is incomplete or unreadable; refusing stale takeover (${lockPath})`);
-      }
-      const state = ownerState(owner, { hostname, inspectProcess, isAlive });
-      if (state !== 'dead') {
-        throw new Error(`${state === 'live' ? 'another refresh run is active' : 'refresh lock owner is ambiguous'} `
-          + `(pid ${owner.pid || '?'}, lock ${lockPath})`);
+      try { owner = JSON.parse(observed.raw); } catch { /* judged below */ }
+      const nowMs = Date.parse(now());
+      let beforeRemove = null;
+      if (!ownerComplete(owner)) {
+        const ageMs = nowMs - newestMtimeMs(lockPath, path.join(lockPath, 'owner.json'));
+        if (!(ageMs > INCOMPLETE_OWNER_RECLAIM_MS)) {
+          throw new Error(`refresh lock owner is incomplete or unreadable; refusing takeover until it is 1 h old `
+            + `(lock ${lockPath}). If no update is running, remove it:  ${removalCommand(lockPath)}`);
+        }
+      } else {
+        const verdict = ownerVerdict(owner, { hostname, inspectProcess, isAlive, nowMs });
+        if (verdict.state !== 'dead') {
+          throw new Error(`${verdict.state === 'live' ? 'another refresh run is active' : 'refresh lock owner is ambiguous'} `
+            + `(pid ${owner.pid || '?'} on ${owner.host || '?'}, started ${owner.startedAt || '?'}, lock ${lockPath}). `
+            + `If no update is running${owner.host && owner.host !== hostname ? ` on ${owner.host}` : ''}, remove it:  ${removalCommand(lockPath)}`);
+        }
+        beforeRemove = (claim) => abandonDeadOwner({ lockPath, owner, hostname, inspectProcess, isAlive, now, claim });
       }
-      abandonDeadOwner({ lockPath, owner, hostname, inspectProcess, isAlive, now });
-      const stale = `${lockPath}.stale-${pid}-${Date.now()}`;
-      try {
-        fs.renameSync(lockPath, stale);
-        fs.rmSync(stale, { recursive: true, force: true });
-      } catch (renameError) {
-        if (renameError?.code !== 'ENOENT') throw renameError;
+      const outcome = removeObservedLock(lockPath, observed, { hostname, beforeRemove, afterClaim: afterTakeoverClaim });
+      if (outcome === 'busy') {
+        throw new Error(`another process is taking over the refresh lock ${lockPath}; refusing to race it (retry shortly)`);
       }
+      // 'removed' or 'changed': acquire again; a changed lock is judged afresh.
     }
   }
   throw new Error(`could not acquire refresh lock ${lockPath}`);
@@ -260,8 +402,14 @@ function atomicJson(file, value) {
   const temporary = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const fd = fs.openSync(temporary, 'wx', 0o600);
-  try { fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
-  fs.renameSync(temporary, file);
+  try {
+    try { fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    // #434: a failed write/rename must not leave a temp behind to block lifecycle retention.
+    try { fs.rmSync(temporary, { force: true }); } catch { /* the original error is the one to report */ }
+    throw error;
+  }
 }
 
 export function openRefreshReceipt({ brainHome, lock, action, desiredVersion = null,

package/kb/verify-citation.mjs

@@ -127,7 +127,20 @@ function samePath(stored, docPath) {
  * takes to reach the hit. A malformed JSON line is skipped, never fatal.
  */
 export async function citationResolves(citation, kbDir) {
-  const files = passagesFilesFor(citation.repo, kbDir);
+  const own = await resolveIn(passagesFilesFor(citation.repo, kbDir), citation.docPath);
+  if (own.resolved) return own;
+  // A capability card is cited under its OWN repo (`repo=ruvector`, `path : ruvector/CARD/ruvector-card`,
+  // kb/card-lane.mjs renderCardHit) but is stored only in the derived `concepts` aggregate, under
+  // `<repo>/CARD/<repo>-card` (scripts/corpus-aggregates.mjs). Look exactly that path up there. Narrow
+  // on purpose: only a `CARD/` path, only in `concepts`, and only the exact stored path.
+  if (/^CARD\/[^/#]+-card$/.test(String(citation.docPath)) && citation.repo !== 'concepts') {
+    const card = await resolveIn(passagesFilesFor('concepts', kbDir), `${citation.repo}/${citation.docPath}`);
+    if (card.resolved) return card;
+  }
+  return own;
+}
+
+async function resolveIn(files, docPath) {
   if (!files.length) return { resolved: false, reason: 'no-store', file: null, storedPath: null };
   for (const file of files) {
     const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
@@ -136,7 +149,7 @@ export async function citationResolves(citation, kbDir) {
         if (!line) continue;
         let rec;
         try { rec = JSON.parse(line); } catch { continue; }
-        if (typeof rec?.path === 'string' && samePath(rec.path, citation.docPath)) {
+        if (typeof rec?.path === 'string' && samePath(rec.path, docPath)) {
           return { resolved: true, reason: 'ok', file: path.basename(file), storedPath: rec.path };
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.20",
+  "version": "4.7.21",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -66,6 +66,7 @@
     "learning:replay:check": "node scripts/learning-replay.mjs --check-portfolio",
     "learning:replay:mutants:check": "node scripts/learning-replay.mjs --check-mutants",
     "learning:replay:dry": "node scripts/learning-replay.mjs --dry-run",
+    "learning:replay:wire": "node scripts/learning-replay.mjs --check-wire",
     "wired:check": "node scripts/wired-check.mjs --check",
     "doc:currency": "node scripts/doc-currency.mjs --check",
     "status:check": "node scripts/status-honesty.mjs",
@@ -107,6 +108,7 @@
     "kb/retrieval-result.mjs",
     "kb/forge-update.mjs",
     "kb/download-retry.mjs",
+    "kb/forge-guard-injection.mjs",
     "kb/corpus-release-identity.mjs",
     "kb/capability-only.mjs",
     "kb/capability-summaries/",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.7.20",
+  "version": "4.7.21",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.20",
+  "version": "4.7.21",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/mcp/managed-cli-interface.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { managedGenerationIdentity } from './managed-cli-generation.mjs';
 import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
+import { resolveRuflo } from '../scripts/ruflo-bin.mjs';
 import { projectDirectory } from '../scripts/project-identity.mjs';
 import { recordManagedCliObservation, recordRegistryLatestObservation } from '../scripts/capability-claim-evidence.mjs';
 
@@ -180,12 +181,19 @@ function writeStamps(executable, argv, env, binding) {
 
 export function resolveManagedExecutable(executable, env = process.env) {
   if (executable !== 'ruflo') return executable;
-  const home = env.HOME || os.homedir();
-  const candidates = [path.join(home, '.npm-global', 'bin', 'ruflo')];
-  if (process.platform === 'win32') candidates.push(`${candidates[0]}.cmd`);
-  return candidates.find((candidate) => {
-    try { fs.accessSync(candidate, fs.constants.X_OK); return true; } catch { return false; }
-  }) || executable;
+  // #420 item 5: same rules as every other Brain caller (RUFLO_BIN is authoritative, then ~/.npm-global/bin, then PATH); this used to check ~/.npm-global only and ignored RUFLO_BIN.
+  return resolveRuflo({ env, home: env.HOME || os.homedir() }) || executable;
+}
+
+/**
+ * ruflo (and claude-flow, the same @claude-flow/cli) self-updates at startup by running `npm install` in its
+ * working directory, which here is the user's project: measured 2026-10-22, a 1.3 GB install landed there.
+ * ruflo-bin.mjs promises every Brain spawn sets CLAUDE_FLOW_AUTO_UPDATE=false; this boundary is a Brain spawn
+ * too. RUFLO_DAEMON_AUTOSTART=0 keeps a background daemon from being left behind in that project.
+ */
+export function managedChildEnv(executable, env) {
+  if (executable !== 'ruflo' && executable !== 'claude-flow') return env;
+  return { ...env, CLAUDE_FLOW_AUTO_UPDATE: 'false', RUFLO_DAEMON_AUTOSTART: '0' };
 }
 
 function quoteWindowsCommandArg(value) {
@@ -323,7 +331,7 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
     if (toolName === 'ruvnet_cli_help') {
       stampKeysForHelp(executable, argv);
       const commandArgv = [...argv, '--help'];
-      const execution = await execute(executable, commandArgv, env);
+      const execution = await execute(executable, commandArgv, managedChildEnv(executable, env));
       if (normalizeManagedExecution(execution).outcome === 'success') writeStamps(executable, argv, env, binding);
       recordManagedCliObservation({ toolName, executable, argv: commandArgv, execution, env });
       return resultOf(executable, commandArgv, execution);
@@ -368,7 +376,7 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
       // host by supplying an arbitrary `host` property.
       const childEnv = (executable === 'agentic-flow' || executable === 'agentic-qe')
         ? runtimeChildEnv({ env, cwd: projectRoot })
-        : env;
+        : managedChildEnv(executable, env);
       if (lifecycle && typeof lifecycle.beforeExecute === 'function') {
         await lifecycle.beforeExecute({ executable, argv, projectRoot, env: childEnv });
       }

package/plugin/scripts/adr-currency-gate.mjs

@@ -33,6 +33,7 @@ import fs from 'node:fs';
 import { execFileSync, spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from './entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO = path.resolve(HERE, '..', '..');
@@ -128,7 +129,7 @@ An ADR describing a world the code left is worse than no ADR: the next reader tr
 }
 
 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/plugin/scripts/advisory-contract.mjs

@@ -0,0 +1,21 @@
+/**
+ * The delivery contract for OPTIONAL Brain advice (#489).
+ *
+ * A capability recommendation, a package recommendation or a routine stack-update notice is
+ * information, not a decision the user must make now. Phrased as a question ("want me to update
+ * it?"), it was promoted by Codex into a structured question dialog that suspended an already
+ * authorized task. So optional advice is worded as statements, and the model-visible context
+ * carries this one line saying so. Real permission gates and genuinely missing information keep
+ * their normal question behaviour; this applies only to optional advisory channels.
+ *
+ * ground-ruvnet.sh cannot import this module and carries the same sentence verbatim;
+ * tests/unit/advisory-contract.test.mjs fails if the two drift.
+ */
+export const ADVISORY_CONTRACT = 'Optional, informational advice: mention it at most once as a statement and continue the current task. '
+  + 'Do not open a question or approval dialog because of it; it grants no authority to install or update anything.';
+
+/**
+ * Question-shaped wording that invites a decision dialog, including the "say X to proceed, or ignore
+ * this" choice prompt the advocacy copy used to carry. Optional advice must match none of it.
+ */
+export const QUESTION_SHAPED = /\?|\b(want me to|would you like|should i|shall i|do you want|can i|to proceed|or ignore this)\b/i;

package/plugin/scripts/advocacy-route.mjs

@@ -61,6 +61,7 @@ import {
   ACTIONS, record, shouldStillOffer, stateHashOf, precision, pendingOffers, reconcileIgnored, loadOutcomes,
 } from './advocacy-outcomes.mjs';
 import { packageRecommenderEnabled, offerNames } from './package-recommender-flag.mjs';
+import { isDirectInvocation } from './entrypoint.mjs';
 // Matcher + socket client load only when the flag is on at process start: default-off pays nothing.
 const PKG = packageRecommenderEnabled() ? { ...(await import('./package-recommender.mjs')), ...(await import('./package-recommender-client.mjs')) } : null;
 
@@ -341,9 +342,9 @@ export function buildCandidate({ prompt, match, availability }) {
     ? `It is already installed here.`
     : `Install state unknown from here — say so rather than claiming it is available.`;
   const copy = [
-    `[RuvNet Brain — capability advocacy] If it genuinely fits, tell the user in ONE sentence: `
-      + `"Consider ${cap.id} — ${cap.benefit}. Say 'use ${cap.id}' to proceed, or ignore this." ${avail}`,
-    `If they accept, the safe first step is \`${cap.nextAction}\` (undo: ${cap.undo}); confirm it with `
+    `[RuvNet Brain — capability advocacy] If it genuinely fits, state it in ONE sentence: `
+      + `"${cap.id} fits here — ${cap.benefit}; 'use ${cap.id}' adopts it." ${avail}`,
+    `If the user later says to use it, the safe first step is \`${cap.nextAction}\` (undo: ${cap.undo}); confirm it with `
       + `search_ruvnet before you build. Say it once, do not expand it, then carry on with the actual work.`,
   ].join('\n');
   return {
@@ -429,7 +430,7 @@ export function decide({ prompt, sessionId, file, state, now = Date.now(), start
 }
 
 // ── CLI ───────────────────────────────────────────────────────────────────────────────────────────
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 
 async function main() {
   const startedAt = Date.now();

package/plugin/scripts/agentdb-recall.mjs

@@ -26,6 +26,7 @@ import { searchOnce, nativeRead, exactReads, searchJsonResult } from './agentdb-
 import { makeLesson } from './lesson-store.mjs';
 import { supersededKeys, tombstonedKeys } from './decision-record.mjs';
 import { checkpointMs, checkpointNamespaces, newestCheckpoint } from './checkpoint-keys.mjs';
+import { isDirectInvocation } from './entrypoint.mjs';
 export const STORE_FILES = Object.freeze(['memory.db']);
 export const DEFAULT_DEADLINE_MS = 1900;
 export const BLOCK_MAX_BYTES = 600;
@@ -115,7 +116,9 @@ function clean(value, limit) {
   return out;
 }
 
-const NOISE_KEY = /^(?:verify[-_]|probe[-_]|test[-_]|rnb-quality-probe|session[-_]|turn[-_]|project-progress[-_]|cevt[-_])/i;
+const MISSING_KNOWLEDGE = /\b(?:cannot\s+(?:be\s+determined|determine)|can(?:'|’)?t\s+(?:be\s+)?determined?|do\s+not\s+know|don(?:'|’)?t\s+know|cannot\s+answer|no\s+(?:verified\s+|supplied\s+|historical\s+)?(?:record|memory|evidence)\s+(?:is\s+)?(?:available|found))\b/i;
+const MISSING_KNOWLEDGE_QUERY = /\b(?:fail(?:ed|ing|ures?)?|missing|unavailable|unknown)\b/i;
+const NOISE_KEY =/^(?:verify[-_]|probe[-_]|test[-_]|rnb-quality-probe|session[-_]|turn[-_]|project-progress[-_]|cevt[-_])/i;
 const SIGNAL_NAMESPACES = new Set(['lessons', 'patterns', 'pattern']);
 /** Turn knowledge is the actual redacted outcome, never its session/transcript wrapper. */
 function turnOutcomeClauses(value, prompt) {
@@ -393,9 +396,10 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
       ...await searchOnce({ ruflo: bin, store: jobStore, deadline: searchDeadline, env, scratch: scratchFor, args, signal }) })));
     let status = results.every((r) => r.state === 'ok') ? 'ok'
       : results.some((r) => r.state === 'timed out') ? 'timed out' : 'unavailable';
-    // Overfetch a bounded six exact values so rejected turn metadata cannot hide
-    // the next useful outcome; at most three verified excerpts are delivered.
-    const candidates = pickRows(results, 6);
+    // Overfetch a bounded twelve exact values (the one search already returns twelve; the exact reads are
+    // one batched reader, so this adds no Ruflo startup) so rejected turn metadata and repeated "cannot
+    // determine" answers cannot hide the next useful outcome (#429); at most three excerpts are delivered.
+    const candidates = pickRows(results, 12);
     // Ruflo previews are ~60 characters. Read the actual selected values within
     // the same deadline so the block contains useful evidence rather than titles.
     const exactResults = await exactReads({ candidates, bin, deadline, env, scratch: scratchFor, signal });
@@ -417,6 +421,12 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
       }
       return { pick: null, state: r.state === 'ok' ? 'unavailable' : r.state };
     }));
+    // A turn that admitted it could not answer is evidence of a failed recall, not the missing fact (#429).
+    // It stays available, after concrete outcomes; a query about failures keeps the ranked order.
+    if (!MISSING_KNOWLEDGE_QUERY.test(prompt)) {
+      const rank = ({ pick }) => Number(pick?.namespace === 'turns' && MISSING_KNOWLEDGE.test(pick.preview));
+      retrieved.sort((a, b) => rank(a) - rank(b));
+    }
     const seenClauses = new Set();
     const picks = retrieved.flatMap(({ pick }) => {
       if (!pick) return [];
@@ -470,7 +480,7 @@ async function main() {
 }
 
 function isMain() {
-  try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 }
 if (isMain()) main().catch(() => process.exit(0));

package/plugin/scripts/automatic-update.mjs

@@ -98,7 +98,15 @@ export function automaticInvocation(args, { source, home = os.homedir(), nodePat
     const coordinator = developerCoordinatorOwner({ home });
     if (coordinator.active) {
       if (!coordinator.ready) throw new Error(`coordinated updater is not ready: ${coordinator.reason}`);
-      return { executable: nodePath, args: [coordinator.entry, '--apply'], source: 'developer-suite', coordinator };
+      // Hooks and timers get knowledge only, never the whole suite (brew, cargo, every npm install) under a session TTL
+      // that kills it mid-install (AuditC #10). The full suite runs only from the scheduled runner, which calls the
+      // coordinator directly, not through here.
+      // The registered snapshot moves only when an --update reconciles it, so it can predate --knowledge-only
+      // (4.7.20 and older refuse it: "unsupported developer update argument", exit 1). Pass the flag only to a
+      // coordinator whose source parses it, as runUpdate does for the updater's --result-file.
+      const knowledgeOnly = fs.readFileSync(coordinator.entry, 'utf8').includes("'--knowledge-only'");
+      return { executable: nodePath, args: [coordinator.entry, '--apply', ...(knowledgeOnly ? ['--knowledge-only'] : [])],
+        source: 'developer-suite', coordinator };
     }
   }
   source ??= updateSource({ home });

package/plugin/scripts/brain-confirmation.mjs

@@ -143,7 +143,8 @@ export function confirm({ footprint, env = process.env, home = os.homedir(), now
   const checkable = Boolean(integrity) && fs.existsSync(path.join(roots.kbDir, 'CORPUS-COVERAGE.json'));
   if (checkable && !integrity.valid) knowledgeProblems.push([`the bytes on disk fail the release-coverage check (${integrity.failures?.[0] || 'unknown'})`, UPDATE]);
   // A newer corpus is published and not yet installed (identity, not age): advisory, never a gate.
-  const pending = newerCorpusPending({ source, corpusCheck: readJson(autoUpdatePaths(roots.brainHome).checkFile) });
+  const pending = newerCorpusPending({ source, corpusCheck: readJson(autoUpdatePaths(roots.brainHome).checkFile),
+    installedAtMs: signed ? Date.parse(signature.verifiedAt || '') : NaN });
   if (pending) {
     const lockAt = readJson(autoUpdatePaths(roots.brainHome).lockFile)?.at;
     const running = Number.isFinite(Date.parse(lockAt || '')) && now - Date.parse(lockAt) < AUTO_UPDATE_LOCK_STALE_MS;