ruvnet-brain 4.7.20 → 4.7.22

package/kb/lifecycle-evidence-retention.mjs

@@ -8,6 +8,15 @@ const TERMINAL_TRANSACTION = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK']);
 const SAFE_ID = /^[A-Za-z0-9._-]+$/;
 const PHASE_FILE = /^\d{3}-[A-Z_]+\.json$/;
 const QUARANTINE = /^\.prune-[A-Za-z0-9._-]+-[a-f0-9]{16}$/;
+// refresh-run.mjs atomicJson(): `<runId>.json.tmp-<pid>-<8 hex>`, written, fsynced, then renamed (#434).
+const ATOMIC_TEMP = /^([A-Za-z0-9._-]+)\.json\.tmp-(\d+)-([a-f0-9]{8})$/;
+// The write+rename takes milliseconds; a temp this old was abandoned by a crash or a failed write,
+// whatever its PID (PIDs are reused, so the age is the evidence, not process liveness).
+export const ABANDONED_TEMP_AGE_MS = 60 * 60 * 1000;
+// Files an operating system or a file browser drops into any folder it shows (Finder, exFAT/SMB shadows,
+// Explorer). They are never evidence and never ours to judge: ignored, and removed when a plain file.
+const VOLUME_METADATA = /^(?:\.DS_Store|\._.*|Thumbs\.db|desktop\.ini)$/i;
+export const isVolumeMetadata = (name) => VOLUME_METADATA.test(String(name));
 
 export const LIFECYCLE_EVIDENCE_RETENTION_POLICY = Object.freeze({
   schemaVersion: 1,
@@ -49,17 +58,85 @@ function stamp(value, label) {
   return parsed;
 }
 
-function scanRefresh(root, unsafe) {
+/**
+ * An abandoned atomic-write temporary (#434) is classified, not treated as foreign evidence. It is
+ * reclaimable only when it is an exclusive regular file older than ABANDONED_TEMP_AGE_MS and either
+ * empty or shadowed by a valid canonical receipt of the same run; a young one is an in-flight write
+ * (left alone), and a non-empty orphan with no canonical receipt is preserved as unsafe.
+ */
+function classifyAtomicTemp(root, file, match, nowMs, unsafe, temporaries) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error('atomic-write temporary is not an exclusive regular file');
+  const identity = { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs };
+  const row = { path: file, runId: match[1], writerPid: Number(match[2]), bytes: stat.size, identity,
+    sha256: crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') };
+  if (!(nowMs - stat.mtimeMs >= ABANDONED_TEMP_AGE_MS)) { temporaries.push({ ...row, disposition: 'in-flight' }); return; }
+  let canonical = false;
+  try {
+    const { value } = regularJson(path.join(root, `${match[1]}.json`));
+    canonical = value?.kind === 'ruvnet-brain-refresh-run' && value.runId === match[1];
+  } catch { /* no valid canonical receipt */ }
+  if (stat.size !== 0 && !canonical) {
+    unsafe.push({ path: file, reason: 'abandoned atomic-write temporary has content and no canonical receipt; preserved' });
+    return;
+  }
+  temporaries.push({ ...row, disposition: 'abandoned', canonicalReceipt: canonical });
+}
+
+/**
+ * A `.prune-<id>-<16 hex>` entry is the rename quarantineAndRemove() makes immediately before it deletes.
+ * Only an interruption between the two leaves one behind (a time-limit kill of the updater is the realistic
+ * cause, 4.7.21 RC2.3). It is reclaimed when it is older than ABANDONED_TEMP_AGE_MS (no prune is still
+ * between rename and delete), has the exact shape this module quarantines (a plain file under refresh-runs;
+ * a directory of phase files under the transactions root), and the run it came from is not live again
+ * (its canonical entry is absent or terminal). Anything else stays unsafe and is preserved, as before.
+ */
+function classifyQuarantine(root, entry, name, kind, nowMs, unsafe, quarantines) {
+  const preserve = (reason) => unsafe.push({ path: entry, reason });
+  try {
+    const stat = fs.lstatSync(entry);
+    const ageMs = nowMs - Math.max(stat.mtimeMs, stat.ctimeMs);
+    if (!(ageMs >= ABANDONED_TEMP_AGE_MS)) return preserve('recognized pruning quarantine remains');
+    const id = /^\.prune-(.+)-[a-f0-9]{16}$/.exec(name)[1];
+    if (kind === 'refresh') {
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return preserve('recognized pruning quarantine remains (not a quarantined receipt)');
+      try {
+        const { value } = regularJson(path.join(root, `${id}.json`));
+        if (!TERMINAL_REFRESH.has(value?.status)) return preserve('recognized pruning quarantine remains (its run is active)');
+      } catch (error) { if (error?.code !== 'ENOENT') return preserve('recognized pruning quarantine remains (its run receipt is unreadable)'); }
+    } else {
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return preserve('recognized pruning quarantine remains (not a quarantined transaction)');
+      const names = fs.readdirSync(entry).filter((file) => !isVolumeMetadata(file));
+      if (names.some((file) => !PHASE_FILE.test(file))) return preserve('recognized pruning quarantine remains (not a quarantined transaction)');
+      if (fs.existsSync(path.join(root, id))) return preserve('recognized pruning quarantine remains (its transaction is present)');
+    }
+    quarantines.push({ path: entry, kind, id, bytes: treeBytes(entry), identity: { dev: stat.dev, ino: stat.ino } });
+  } catch (error) { preserve(`recognized pruning quarantine remains (${error.message})`); }
+}
+
+function scanRefresh(root, unsafe, temporaries = [], nowMs = Date.now(), extras = { quarantines: [], foreign: [], volumeMetadata: [] }) {
   if (!fs.existsSync(root)) return [];
   const rows = [];
   for (const name of fs.readdirSync(root).sort()) {
     const file = path.join(root, name);
+    if (isVolumeMetadata(name)) { extras.volumeMetadata.push(file); continue; }
     if (QUARANTINE.test(name)) {
-      unsafe.push({ path: file, reason: 'recognized pruning quarantine remains' });
+      classifyQuarantine(root, file, name, 'refresh', nowMs, unsafe, extras.quarantines);
+      continue;
+    }
+    const temp = ATOMIC_TEMP.exec(name);
+    if (temp) {
+      try { classifyAtomicTemp(root, file, temp, nowMs, unsafe, temporaries); } catch (error) { unsafe.push({ path: file, reason: error.message }); }
       continue;
     }
     try {
-      if (!name.endsWith('.json')) throw new Error('unexpected refresh evidence entry');
+      if (!name.endsWith('.json')) {
+        // Not evidence and not ours (a note, a copy someone made): reported and kept, never a reason to
+        // fail an update. Only a non-file (directory, link, device) stays unsafe.
+        const stat = fs.lstatSync(file);
+        if (stat.isFile() && !stat.isSymbolicLink()) { extras.foreign.push({ path: file, bytes: stat.size }); continue; }
+        throw new Error('unexpected refresh evidence entry');
+      }
       const { value: receipt, bytes } = regularJson(file);
       const runId = name.slice(0, -5);
       if (!SAFE_ID.test(runId) || receipt?.schemaVersion !== 3 || receipt?.kind !== 'ruvnet-brain-refresh-run'
@@ -73,21 +150,25 @@ function scanRefresh(root, unsafe) {
   return rows;
 }
 
-function scanTransactions(root, unsafe) {
+function scanTransactions(root, unsafe, nowMs = Date.now(), extras = { quarantines: [], foreign: [], volumeMetadata: [] }) {
   if (!fs.existsSync(root)) return [];
   const rows = [];
   for (const name of fs.readdirSync(root).sort()) {
     const dir = path.join(root, name);
+    if (isVolumeMetadata(name)) { extras.volumeMetadata.push(dir); continue; }
     if (QUARANTINE.test(name)) {
-      unsafe.push({ path: dir, reason: 'recognized pruning quarantine remains' });
+      classifyQuarantine(root, dir, name, 'transaction', nowMs, unsafe, extras.quarantines);
       continue;
     }
     try {
       const stat = fs.lstatSync(dir);
+      if (stat.isFile() && !stat.isSymbolicLink()) { extras.foreign.push({ path: dir, bytes: stat.size }); continue; }
       if (!SAFE_ID.test(name) || !stat.isDirectory() || stat.isSymbolicLink()) {
         throw new Error('malformed transaction evidence entry');
       }
-      const names = fs.readdirSync(dir).sort();
+      const all = fs.readdirSync(dir).sort();
+      for (const file of all) if (isVolumeMetadata(file)) extras.volumeMetadata.push(path.join(dir, file));
+      const names = all.filter((file) => !isVolumeMetadata(file));
       if (!names.length || names.some((file) => !PHASE_FILE.test(file))) throw new Error('transaction phase inventory is malformed');
       const phases = names.map((file) => regularJson(path.join(dir, file)).value);
       const latest = phases.at(-1);
@@ -137,8 +218,11 @@ function trustedEvidenceRoot(root, unsafe) {
 function snapshot(options) {
   const roots = rootsFor(options);
   const unsafe = [];
-  const refresh = trustedEvidenceRoot(roots.refresh, unsafe) ? scanRefresh(roots.refresh, unsafe) : [];
-  const transactions = trustedEvidenceRoot(roots.transactions, unsafe) ? scanTransactions(roots.transactions, unsafe) : [];
+  const temporaries = [];
+  const extras = { quarantines: [], foreign: [], volumeMetadata: [] };
+  const nowMs = Date.parse((options.now || (() => new Date().toISOString()))());
+  const refresh = trustedEvidenceRoot(roots.refresh, unsafe) ? scanRefresh(roots.refresh, unsafe, temporaries, nowMs, extras) : [];
+  const transactions = trustedEvidenceRoot(roots.transactions, unsafe) ? scanTransactions(roots.transactions, unsafe, nowMs, extras) : [];
   const preserveRefresh = new Set((options.preserveRefreshRunIds || []).map(String));
   const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => physicalPath(entry)));
   const protectedRefresh = new Map();
@@ -170,11 +254,11 @@ function snapshot(options) {
     if (preserveTransactions.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'explicitly preserved transaction');
     if (retainedTransactionPaths.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
   }
-  const bytes = [...refresh, ...transactions].reduce((sum, row) => sum + row.bytes, 0)
+  const bytes = [...refresh, ...transactions, ...temporaries, ...extras.quarantines].reduce((sum, row) => sum + row.bytes, 0)
     + unsafe.filter(({ reason }) => /quarantine remains/.test(reason)).reduce((sum, { path: entry }) => {
       try { return sum + treeBytes(entry); } catch { return sum; }
     }, 0);
-  return { roots, unsafe, refresh, transactions, bytes, protectedRefresh, protectedTransactions };
+  return { roots, unsafe, refresh, transactions, temporaries, bytes, protectedRefresh, protectedTransactions, ...extras };
 }
 
 function counts(state) {
@@ -202,6 +286,10 @@ export function assessLifecycleEvidence(options = {}) {
         && !state.protectedTransactions.has(row.path)).sort((a, b) => a.timestamp - b.timestamp)
         .map(({ path: entryPath }) => entryPath),
     },
+    abandonedTemporaries: state.temporaries.filter((row) => row.disposition === 'abandoned')
+      .map(({ path: entryPath, runId, writerPid, bytes, sha256, canonicalReceipt }) => ({ path: entryPath, runId, writerPid, bytes, sha256, canonicalReceipt })),
+    abandonedQuarantines: state.quarantines.map(({ path: entryPath, kind, id, bytes }) => ({ path: entryPath, kind, id, bytes })),
+    foreign: state.foreign, volumeMetadata: state.volumeMetadata,
     removed: { refresh: [], transactions: [] }, after: counts(state), unsafe: state.unsafe,
     withinBudget: isWithin(state, policy) };
 }
@@ -213,9 +301,11 @@ function quarantineAndRemove(entry, root, removeEntry, afterQuarantine) {
     throw new Error(`refusing unsafe lifecycle evidence removal: ${entry}`);
   }
   const quarantine = path.join(root, `.prune-${name.replace(/\.json$/, '')}-${crypto.randomBytes(8).toString('hex')}`);
-  fs.renameSync(resolved, quarantine);
+  // Vanished since the snapshot (another sweep, the writer itself): already gone, not a failed prune.
+  try { fs.renameSync(resolved, quarantine); } catch (error) { if (error?.code === 'ENOENT') return false; throw error; }
   afterQuarantine?.({ entry: resolved, quarantine });
   removeEntry(quarantine);
+  return true;
 }
 
 // Keep every JSON token (including numeric precision and escaped string spelling).
@@ -223,6 +313,7 @@ function quarantineAndRemove(entry, root, removeEntry, afterQuarantine) {
 function compactTerminalPhases(row) {
   const compacted = [];
   for (const name of fs.readdirSync(row.path).sort()) {
+    if (isVolumeMetadata(name)) continue;
     const file = path.join(row.path, name);
     const stat = fs.lstatSync(file);
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error('phase is not an exclusive regular file');
@@ -257,6 +348,7 @@ function compactTerminalPhases(row) {
   return compacted;
 }
 
+export const MAX_VANISHED_RETRIES = 64;
 export function pruneLifecycleEvidence(options = {}) {
   const policy = options.policy || LIFECYCLE_EVIDENCE_RETENTION_POLICY;
   const removeEntry = options.removeEntry || ((entry) => fs.rmSync(entry, { recursive: true, force: true }));
@@ -265,6 +357,40 @@ export function pruneLifecycleEvidence(options = {}) {
   // the exact entry it just quarantined. Recovery must not guess away private data.
   const initial = assessLifecycleEvidence({ ...options, policy });
   const removed = { refresh: [], transactions: [] };
+  // #434: reclaim abandoned atomic-write temporaries first (reported with size and sha256, never
+  // silent). The file identity is rechecked immediately before it is quarantined.
+  const reclaimedTemporaries = [];
+  for (const row of snapshot(options).temporaries.filter((entry) => entry.disposition === 'abandoned')) {
+    let current;
+    // A temp that vanished between the snapshot and this re-check is already gone; it must not throw the whole prune.
+    try { current = fs.lstatSync(row.path); } catch (error) { if (error?.code === 'ENOENT') continue; throw error; }
+    if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || current.dev !== row.identity.dev
+      || current.ino !== row.identity.ino || current.size !== row.identity.size || current.mtimeMs !== row.identity.mtimeMs) continue;
+    if (!quarantineAndRemove(row.path, path.dirname(row.path), removeEntry, options.afterQuarantine)) continue;
+    reclaimedTemporaries.push({ path: row.path, runId: row.runId, writerPid: row.writerPid, bytes: row.bytes,
+      sha256: row.sha256, canonicalReceipt: row.canonicalReceipt });
+  }
+  // Volume metadata (.DS_Store and friends) is removed when it is a plain file; anything else by that
+  // name is left alone (it was never counted as evidence either way).
+  const removedVolumeMetadata = [];
+  for (const entry of snapshot(options).volumeMetadata) {
+    try {
+      const stat = fs.lstatSync(entry);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      fs.rmSync(entry, { force: true });
+      removedVolumeMetadata.push(entry);
+    } catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  }
+  // Abandoned quarantines of this module's own interrupted prunes (classifyQuarantine), identity re-checked
+  // immediately before removal and reported, never silent.
+  const reclaimedQuarantines = [];
+  for (const row of snapshot(options).quarantines) {
+    let current;
+    try { current = fs.lstatSync(row.path); } catch (error) { if (error?.code === 'ENOENT') continue; throw error; }
+    if (current.isSymbolicLink() || current.dev !== row.identity.dev || current.ino !== row.identity.ino) continue;
+    removeEntry(row.path);
+    reclaimedQuarantines.push({ path: row.path, kind: row.kind, id: row.id, bytes: row.bytes });
+  }
   const compacted = [];
   const compactState = snapshot(options);
   if (!compactState.unsafe.length && compactState.bytes > policy.maxEvidenceBytes) {
@@ -272,6 +398,10 @@ export function pruneLifecycleEvidence(options = {}) {
       compacted.push(...compactTerminalPhases(row));
     }
   }
+  // Review r2 (4.7.21): an entry that "vanishes" on every rename (a filesystem that keeps listing it, a writer that
+  // keeps recreating it) must not spin this loop forever. Bounded; when the bound trips, pruning stops (fails closed:
+  // nothing more is removed) and the reason is returned.
+  let vanishedRetries = 0; let stopped = null;
   for (;;) {
     const state = snapshot(options);
     if (isWithin(state, policy)) break;
@@ -285,10 +415,17 @@ export function pruneLifecycleEvidence(options = {}) {
         : [...refreshCandidates, ...transactionCandidates].sort((a, b) => a.timestamp - b.timestamp)[0];
     if (!candidate) break;
     const root = candidate.kind === 'refresh' ? state.roots.refresh : state.roots.transactions;
-    quarantineAndRemove(candidate.path, root, removeEntry, options.afterQuarantine);
+    if (!quarantineAndRemove(candidate.path, root, removeEntry, options.afterQuarantine)) { // gone: re-snapshot
+      vanishedRetries += 1;
+      if (vanishedRetries > MAX_VANISHED_RETRIES) {
+        stopped = `pruning stopped: lifecycle evidence vanished ${vanishedRetries} times while being removed (last: ${candidate.path}); nothing further was removed`;
+        break;
+      }
+      continue;
+    }
     removed[candidate.kind === 'refresh' ? 'refresh' : 'transactions'].push(candidate.path);
   }
   const final = assessLifecycleEvidence({ ...options, policy });
-  return { ...final, before: initial.before, removed, compacted,
-    after: final.after, withinBudget: final.withinBudget };
+  return { ...final, before: initial.before, removed, reclaimedTemporaries, reclaimedQuarantines, removedVolumeMetadata, compacted,
+    after: final.after, withinBudget: final.withinBudget, ...(stopped ? { stopped } : {}) };
 }

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.22",
   "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.22",
   "author": {
     "name": "Stuart Kerr"
   },

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

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