ruvnet-brain 4.7.20 → 4.7.21

package/kb/forge-update.mjs

@@ -25,7 +25,7 @@ import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
-import { fetchJsonWithRetry, fetchBytesWithRetry } from './download-retry.mjs';
+import { fetchJsonWithRetry, fetchBytesWithRetry, downloadFileWithRetry } from './download-retry.mjs';
 import { extractZip, zipDeclaredBytes } from './zip-extract.mjs';
 import { applyBrainProfile, discoverStoreFamilies, readBrainProfile } from './brain-profile.mjs';
 import { acquireRefreshLock, releaseRefreshLock } from './refresh-run.mjs';
@@ -80,11 +80,26 @@ const SIGNING_PUBKEY_PEM = `-----BEGIN PUBLIC KEY-----
 MCowBQYDK2VwAyEAgse9TAtehXUvUfTrJFY2CCHiCbmelR8yCgS//sen5/w=
 -----END PUBLIC KEY-----`;
 
+// Hash a file in fixed-size chunks: the bundle is ~745 MB and must never be held in memory whole.
+function digestFile(file, algorithms = ['sha256']) {
+  const hashes = algorithms.map((algorithm) => [algorithm, createHash(algorithm)]);
+  const chunk = Buffer.allocUnsafe(8 * 1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  let bytes = 0;
+  try {
+    for (let read; (read = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0;) {
+      bytes += read;
+      for (const [, hash] of hashes) hash.update(chunk.subarray(0, read));
+    }
+  } finally { fs.closeSync(fd); }
+  return { bytes, digests: Object.fromEntries(hashes.map(([algorithm, hash]) => [algorithm, hash.digest('hex')])) };
+}
+
 export function verifyDownloadedBundle(bundlePath, signaturePath) {
   try {
     if (!fs.existsSync(bundlePath)) return { ok: false, reason: `bundle not found: ${bundlePath}` };
     if (!fs.existsSync(signaturePath)) return { ok: false, reason: 'signature missing (fail-closed)' };
-    const digest = createHash('sha256').update(fs.readFileSync(bundlePath)).digest('hex');
+    const digest = digestFile(bundlePath).digests.sha256;
     const ok = verifySignature(null, Buffer.from(digest, 'hex'), createPublicKey(SIGNING_PUBKEY_PEM), fs.readFileSync(signaturePath));
     return ok ? { ok: true, reason: `signature valid (sha256 ${digest.slice(0, 12)}…)` }
       : { ok: false, reason: 'signature does NOT match — bundle may be tampered' };
@@ -103,11 +118,20 @@ let updateLock = null;
 let updateOutcomeWritten = false;
 let lifecycleRetention = null;
 let legacyBackupRetention = null;
+// The bundle's temp directory (zip, signature, extraction). Removed on EVERY exit, including die() and a signal.
+let downloadDir = null;
 
-function writeUpdateOutcome(outcome) {
+/**
+ * Lifecycle-evidence retention is housekeeping of receipts ABOUT updates. It never changes the verdict of
+ * the update itself (4.7.21 RC2.3): a `.DS_Store` or a stranded quarantine used to turn every applied and
+ * no-op run into `recovery-required` exit 1, and the installer then re-downloaded 745 MB every night into
+ * the same wall. Over budget or unsafe evidence is recorded as `retentionAdvisory`, and the verdict and exit
+ * code stay exactly what the update produced.
+ */
+function writeUpdateOutcome(outcome, { prune = true } = {}) {
   if (updateOutcomeWritten) return outcome;
   if (legacyBackupRetention) outcome = { ...outcome, legacyBackupRetention };
-  if (!lifecycleRetention) {
+  if (!lifecycleRetention && prune) {
     try {
       lifecycleRetention = pruneLifecycleEvidence({ brainHome: path.dirname(KB_DIR), kbDir: KB_DIR,
         preserveRefreshRunIds: updateLock?.runId ? [updateLock.runId] : [],
@@ -117,10 +141,14 @@ function writeUpdateOutcome(outcome) {
         withinBudget: false, unsafe: [{ path: path.dirname(KB_DIR), reason: error.message }] };
     }
   }
-  const finalOutcome = lifecycleRetention.withinBudget === true ? { ...outcome, lifecycleRetention }
-    : { ...outcome, terminalVerdict: 'recovery-required', exitCode: 1,
-      reason: `lifecycle evidence retention failed: ${lifecycleRetention.unsafe?.map(({ reason }) => reason).join('; ') || 'budget exceeded'}`,
-      lifecycleRetention };
+  let finalOutcome = lifecycleRetention ? { ...outcome, lifecycleRetention } : outcome;
+  if (lifecycleRetention && lifecycleRetention.withinBudget !== true) {
+    const retentionAdvisory = { withinBudget: false,
+      reason: `lifecycle evidence retention is over budget or unsafe: ${lifecycleRetention.unsafe?.map(({ path: entry, reason }) => `${entry}: ${reason}`).join('; ') || 'budget exceeded'}`,
+      unsafe: lifecycleRetention.unsafe?.length || 0, foreign: lifecycleRetention.foreign?.length || 0 };
+    finalOutcome = { ...finalOutcome, retentionAdvisory };
+    console.error(`\n  ⚠ advisory (the update verdict is unchanged): ${retentionAdvisory.reason}`);
+  }
   if (!RESULT_FILE) return finalOutcome;
   fs.mkdirSync(path.dirname(RESULT_FILE), { recursive: true });
   atomicJson(RESULT_FILE, { schemaVersion: 1, kind: 'ruvnet-brain-update-result',
@@ -158,7 +186,24 @@ export function releaseUpdateLock(lock = updateLock) {
   return released;
 }
 
-process.on('exit', () => { releaseUpdateLock(); });
+process.on('exit', () => {
+  releaseUpdateLock();
+  if (downloadDir) { try { fs.rmSync(downloadDir, { recursive: true, force: true }); } catch { /* best effort at exit */ } }
+});
+
+// A time-limit kill (SessionStart TTL, the nightly runner) sends SIGTERM to the process group. Without a
+// handler Node exits without running 'exit' listeners, so the update lock stayed behind and the result
+// file never said why. Settle the same way die() does: record the outcome, keep any rollback copy, exit.
+function interruptedBySignal(signal) {
+  const exitCode = signal === 'SIGINT' ? 130 : 143;
+  console.error(`\n[forge-update] interrupted by ${signal} — the live KB is left as the storage transaction left it.`);
+  // --check records only its currency verdict; an interrupted poll has none to record.
+  if (APPLY || STAGED_RELEASE_FILE) {
+    try { writeUpdateOutcome({ terminalVerdict: 'interrupted', exitCode, reason: `interrupted by ${signal}` }, { prune: false }); } catch { /* exit wins */ }
+  }
+  try { settleRollback({ reclaimable: false, keepReason: `the update was interrupted by ${signal}` }); } catch { /* exit wins */ }
+  process.exit(exitCode);
+}
 function settleRollback({ reclaimable, keepReason = null, intentionallyRemovedStores = [] }) {
   if (rollbackSettled) return;
   rollbackSettled = true;
@@ -781,12 +826,28 @@ async function fetchJson(url) {
     die(`network failure fetching ${url}: ${error.message} — nothing changed locally.`, 2);
   }
 }
+function downloadFailed(error, url, kind, failureCode) {
+  if (error.status) die(`${kind} download returned HTTP ${error.status} for ${url} — nothing changed.`, failureCode);
+  die(`network failure downloading ${kind} ${url}: ${error.message} — nothing changed locally.`, failureCode);
+}
 async function fetchBuffer(url, { failureCode = 2, kind = 'bundle' } = {}) {
-  try { return await fetchBytesWithRetry(url); }
-  catch (error) {
-    if (error.status) die(`${kind} download returned HTTP ${error.status} for ${url} — nothing changed.`, failureCode);
-    die(`network failure downloading ${kind} ${url}: ${error.message} — nothing changed locally.`, failureCode);
-  }
+  try { return await fetchBytesWithRetry(url, { deadlineMs: 5 * 60_000 }); }
+  catch (error) { downloadFailed(error, url, kind, failureCode); }
+}
+// The bundle streams to disk: no-progress timeout, Range resume across retries, and a deadline scaled to
+// its size (kb/download-retry.mjs) — never the old whole-attempt 5-minute cap over a buffer in memory.
+async function fetchFile(url, destination, { failureCode = 2, kind = 'bundle' } = {}) {
+  let lastShown = -1;
+  try {
+    await downloadFileWithRetry(url, destination, {
+      headers: { 'User-Agent': 'ruvnet-brain-updater', Accept: 'application/octet-stream' },
+      onRetry: ({ attempt, error }) => console.error(`  download interrupted (${error.message}); retry ${attempt + 1}/3, resuming where it stopped when the server allows`),
+      onProgress: ({ received, total }) => {
+        const pct = total ? Math.floor(received / total * 10) * 10 : -1;
+        if (total && pct !== lastShown) { lastShown = pct; console.log(`  …${pct}% (${(received / 1e6).toFixed(0)} MB / ${(total / 1e6).toFixed(0)} MB)`); }
+      },
+    });
+  } catch (error) { downloadFailed(error, url, kind, failureCode); }
 }
 
 // The canonical manifest can be ONE of three shapes — handle all three:
@@ -1053,9 +1114,48 @@ function dirSize(dir) {
 // A backup-looking name and matching RVF paths are not evidence that its other
 // bytes are disposable. Legacy backups have no authenticated complete ownership
 // receipt: reclaim only a tree whose every entry survives identically in live.
-function assertRedundantBackup(backup, live) {
-  const compare = (prior, current) => {
+//
+// #335: `archives` are `--clean --archive` trees (<kb>.archive/<stamp>/<copy>/). A regular file whose exact
+// bytes sit at the same relative path in one of them is accounted for even when live lacks or changed it.
+function assertRedundantBackup(backup, live, archives = []) {
+  const quiet = (file) => { try { return fs.lstatSync(file); } catch { return null; } };
+  // A reference (live or archive) counts only as a regular file reached through real directories, no link at
+  // the root or any ancestor, whose real path is outside the backup being judged: a link into the backup would
+  // compare the backup with itself and approve deleting its only copy (cross-vendor review A).
+  const realBackup = (() => { try { return fs.realpathSync(backup); } catch { return path.resolve(backup); } })();
+  const insideBackup = (file) => {
+    let real; try { real = fs.realpathSync(file); } catch { return true; }
+    return real === realBackup || real.startsWith(`${realBackup}${path.sep}`);
+  };
+  const reference = (root, relative) => {
+    let dir = root;
+    for (const part of ['', ...relative.split(path.sep).slice(0, -1)]) {
+      dir = part ? path.join(dir, part) : dir;
+      const st = quiet(dir);
+      if (!st || !st.isDirectory() || st.isSymbolicLink()) return null;
+    }
+    const file = path.join(root, relative); const st = quiet(file);
+    return st && st.isFile() && !st.isSymbolicLink() && !insideBackup(file) ? { file, st } : null;
+  };
+  const archived = (relative, prior, size) => archives.some((root) => {
+    const ref = reference(root, relative);
+    return Boolean(ref && ref.st.size === size && sha256File(ref.file) === sha256File(prior));
+  });
+  const compare = (prior, current, relative = '') => {
     const a = fs.lstatSync(prior);
+    if (archives.length && !a.isSymbolicLink() && (a.isFile() || a.isDirectory())) {
+      if (a.isDirectory()) {
+        for (const name of fs.readdirSync(prior)) {
+          if (/^(?:\._|\.DS_Store$)/.test(name)) continue;
+          compare(path.join(prior, name), path.join(current, name), path.join(relative, name));
+        }
+        return;
+      }
+      const ref = reference(live, relative);
+      const same = ref && a.size === ref.st.size && sha256File(prior) === sha256File(ref.file);
+      if (same || archived(relative, prior, a.size)) return;
+      throw new Error(`different bytes: ${prior}`);
+    }
     const b = fs.lstatSync(current);
     if (a.isSymbolicLink() || b.isSymbolicLink()) {
       // Compare links themselves, never dereference them. Store symlinks are
@@ -1068,7 +1168,7 @@ function assertRedundantBackup(backup, live) {
       // written by an exFAT/FAT round trip is not Brain data, so it is never what makes a copy unique.
       for (const name of fs.readdirSync(prior)) {
         if (/^(?:\._|\.DS_Store$)/.test(name)) continue;
-        compare(path.join(prior, name), path.join(current, name));
+        compare(path.join(prior, name), path.join(current, name), path.join(relative, name));
       }
     } else if (a.isFile() && b.isFile()) {
       if (a.size !== b.size || sha256File(prior) !== sha256File(current)) {
@@ -1183,6 +1283,12 @@ export function reclaimBackups({
   const safePreserved = new Map();
   const retentionPolicy = rollbackRetentionPolicy(kbDir, env);
   const liveInventory = storeInventory(kbDir);
+  // #335: trees written by the explicit `npx ruvnet-brain --clean --archive` (never automatically).
+  const realDir = (dir) => { try { const st = fs.lstatSync(dir); return st.isDirectory() && !st.isSymbolicLink(); } catch { return false; } };
+  const listDirs = (dir) => { try { return fs.readdirSync(dir).sort().map((n) => path.join(dir, n)).filter(realDir); } catch { return []; } };
+  const archiveDir = path.join(parent, `${base}.archive`);
+  // A dot-named entry is an archive still being written, or one a killed sweep left half-written: never a reference.
+  const archives = realDir(archiveDir) ? listDirs(archiveDir).flatMap(listDirs).filter((dir) => !path.basename(dir).startsWith('.')) : [];
 
   // A store the live release's own COVERAGE.json marks ineligible is absent from live BY POLICY
   // (excluded-no-corpus, fork, archived…), not lost by an update; its presence in a backup must not
@@ -1234,6 +1340,19 @@ export function reclaimBackups({
         if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`not a real directory: ${dir}`);
       }
     } catch (error) { kept.push([b, `unsafe reclaim target: ${error.message}`]); continue; }
+    // #335: a copy whose every byte survives in live or in an archive tree is accounted for, whatever
+    // its store inventory says; anything still unproven falls through to the unchanged checks below.
+    let archivedCopy = false;
+    if (archives.length && liveInventory.complete) {
+      try { assertRedundantBackup(b, kbDir, archives); archivedCopy = true; } catch { /* not fully accounted for */ }
+    }
+    if (archivedCopy) {
+      const size = dirSize(b);
+      if (dryRun) { wouldRemove.push(b); freed += size; continue; }
+      try { fs.rmSync(b, { recursive: true, force: true }); removed.push(b); freed += size; }
+      catch (e) { kept.push([b, `could not remove: ${e.message}`]); }
+      continue;
+    }
     const backupInventory = storeInventory(b);
     if (!liveInventory.complete || !backupInventory.complete) {
       kept.push([b, `inventory is incomplete; refusing destructive reclaim (${backupInventory.reason || liveInventory.reason || 'unknown'})`]);
@@ -1423,14 +1542,26 @@ function archiveVerifierFromDigests(actualDigests, bytes) {
 
 // Capture the closed transaction algorithm inventory synchronously. Never retain mutable bytes:
 // the capability attests only to this creation-time snapshot, not a later caller-owned Buffer.
-export function createDownloadedArchiveVerifier(downloadedBuffer, expectedDigests = []) {
-  if (!Buffer.isBuffer(downloadedBuffer) || !Array.isArray(expectedDigests)) throw new TypeError('archive bytes and digest inventory required');
+function archiveAlgorithms(expectedDigests) {
   const algorithms = new Set(['sha256']);
   for (const expected of expectedDigests) {
     if (expected == null) continue;
     if (typeof expected !== 'string' || !expected) throw new TypeError('invalid archive digest');
     algorithms.add(expected.includes(':') ? expected.split(':')[0] : 'sha256');
   }
+  return algorithms;
+}
+
+/** The same capability, computed from the downloaded file in chunks (the bundle is never held in memory). */
+export function createDownloadedArchiveVerifierFromFile(file, expectedDigests = []) {
+  if (typeof file !== 'string' || !Array.isArray(expectedDigests)) throw new TypeError('archive path and digest inventory required');
+  const { bytes, digests } = digestFile(file, [...archiveAlgorithms(expectedDigests)]);
+  return archiveVerifierFromDigests(Object.freeze(digests), bytes);
+}
+
+export function createDownloadedArchiveVerifier(downloadedBuffer, expectedDigests = []) {
+  if (!Buffer.isBuffer(downloadedBuffer) || !Array.isArray(expectedDigests)) throw new TypeError('archive bytes and digest inventory required');
+  const algorithms = archiveAlgorithms(expectedDigests);
   const actualDigests = Object.freeze(Object.fromEntries([...algorithms].map(algorithm =>
     [algorithm, createHash(algorithm).update(downloadedBuffer).digest('hex')])));
   return archiveVerifierFromDigests(actualDigests, downloadedBuffer.length);
@@ -1658,13 +1789,11 @@ async function main() {
   if (verdict.verdict === 'REFUSED') {
     console.log(`REFUSED — ${verdict.reason}`);
     console.log('Nothing was downloaded; the live brain is untouched.');
-    const refusedOutcome = APPLY
-      ? writeUpdateOutcome({ terminalVerdict: 'refused', reason: verdict.reason,
+    if (APPLY) writeUpdateOutcome({ terminalVerdict: 'refused', reason: verdict.reason,
         currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
-        storeCount: targets.length })
-      : writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
-        candidateKind: candidateIdentity.kind, candidateTag: candidateIdentity.tag, storeCount: targets.length });
-    if (refusedOutcome?.terminalVerdict === 'recovery-required') die(refusedOutcome.reason);
+        storeCount: targets.length });
+    else writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
+      candidateKind: candidateIdentity.kind, candidateTag: candidateIdentity.tag, storeCount: targets.length });
     process.exit(0);
   }
 
@@ -1703,11 +1832,10 @@ async function main() {
     if (!installed.valid) die(`already-current KB failed integrity: ${installed.failures.join('; ')}`);
     // No transaction paths are created: the inventory still counts every retained managed copy.
     const measuredDelta = storageDelta({ live: KB_DIR }, { prior: inventoryBefore.active, inventoryBefore });
-    const noopOutcome = writeUpdateOutcome({ terminalVerdict: 'noop', reason: 'already-current', storeCount: targets.length,
+    writeUpdateOutcome({ terminalVerdict: 'noop', reason: 'already-current', storeCount: targets.length,
       currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
       storageDelta: measuredDelta,
       phaseEvidence: phaseEvidenceFor({ root: KB_DIR, terminalVerdict: 'noop', storageDelta: measuredDelta }) });
-    if (noopOutcome?.terminalVerdict === 'recovery-required') die(noopOutcome.reason);
     console.log(`\nNothing to apply — already current.`); process.exit(0);
   }
 
@@ -1741,27 +1869,26 @@ async function main() {
   const originLabel = resolved.origin === 'latest-release-asset' ? `live release asset "${resolved.assetName}"`
     : resolved.origin === 'live-manifest' ? 'live manifest' : 'PINNED FALLBACK (see warning above)';
   console.log(`\n[${behindStores.length} store(s)] downloading ${resolved.url}\n  (source: ${originLabel}) ...`);
-  let buf = await fetchBuffer(resolved.url);
-  const sigBuf = await fetchBuffer(`${resolved.url}.sig`, { failureCode: 3, kind: 'signature' });
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-update-release-'));
+  downloadDir = tmp;
   const zipPath = path.join(tmp, 'bundle.zip');
   const sigPath = path.join(tmp, 'bundle.zip.sig');
   const extractDir = path.join(tmp, 'extracted');
-  fs.writeFileSync(zipPath, buf);
+  await fetchFile(resolved.url, zipPath);
+  const sigBuf = await fetchBuffer(`${resolved.url}.sig`, { failureCode: 3, kind: 'signature' });
   fs.writeFileSync(sigPath, sigBuf);
   fs.mkdirSync(extractDir);
-  console.log(`  downloaded ${(buf.length / 1e6).toFixed(1)} MB.`);
+  console.log(`  downloaded ${(fs.statSync(zipPath).size / 1e6).toFixed(1)} MB.`);
   const signature = verifyDownloadedBundle(zipPath, sigPath);
   if (!signature.ok) { fs.rmSync(tmp, { recursive: true, force: true }); die(`✗ SIGNATURE VERIFICATION FAILED: ${signature.reason}`, 4); }
   console.log(`  ✓ signature verified — ${signature.reason}`);
   let archiveVerifier;
-  try { archiveVerifier = createDownloadedArchiveVerifier(buf, resolvedTargets.map(({ resolved: target }) => target.digest)); }
+  try { archiveVerifier = createDownloadedArchiveVerifierFromFile(zipPath, resolvedTargets.map(({ resolved: target }) => target.digest)); }
   catch (error) {
     fs.rmSync(tmp, { recursive: true, force: true });
     die(`archive digest snapshot failed: ${error.message} — local files untouched.`, 4);
   }
   const bundleSha256 = archiveVerifier.digest();
-  buf = null; // Snapshot owns only immutable digest strings; release the downloaded bytes before validation.
   // DISK-SPACE PREFLIGHT, before a single byte is unpacked: the bundle unpacks in temp, then a whole
   // candidate generation is built beside the live one: the bundle, plus what prepareCandidate carries into
   // it from live — node_modules, and every private/local-ingest store file (restorePrivateFilesIntoCandidate
@@ -1916,12 +2043,11 @@ async function main() {
   fs.rmSync(tmp, { recursive: true, force: true });
   console.log(`  storage transaction: ${transaction.terminalVerdict}`);
   if (transaction.terminalVerdict === 'cleanup-pending') {
-    const cleanupOutcome = writeUpdateOutcome({ terminalVerdict: 'cleanup-pending', storageDelta: transaction.storageDelta,
+    writeUpdateOutcome({ terminalVerdict: 'cleanup-pending', storageDelta: transaction.storageDelta,
       transactionReceipts: transaction.paths.receipts, bundleSha256,
       phaseEvidence: phaseEvidenceFor({ root: KB_DIR, terminalVerdict: 'cleanup-pending', bundleSha256,
         transactionReceipts: transaction.paths.receipts, overlay: privateOverlay,
         storageDelta: transaction.storageDelta }) });
-    if (cleanupOutcome?.terminalVerdict === 'recovery-required') die(cleanupOutcome.reason);
     console.error('\nVerified live generation is active, but redundant rollback cleanup is pending.');
     process.exitCode = 12;
     return;
@@ -1986,7 +2112,7 @@ async function main() {
     console.log(`\n${unchangedStores.length} of ${behindStores.length} store(s) were already at the canonical build and did not change: ${unchangedStores.join(', ')}`);
     console.log(`  (stores are forged independently — an unchanged store means its upstream repo did not move, not a failed update.)`);
   }
-  const finalOutcome = writeUpdateOutcome({ terminalVerdict: transaction.terminalVerdict, storeCount: behindStores.length, retiredStores,
+  writeUpdateOutcome({ terminalVerdict: transaction.terminalVerdict, storeCount: behindStores.length, retiredStores,
     currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
     storageDelta: transaction.storageDelta,
     transactionReceipts: transaction.paths.receipts,
@@ -1996,7 +2122,6 @@ async function main() {
       bundleSha256,
       transactionReceipts: transaction.paths.receipts, overlay: privateOverlay,
       storageDelta: transaction.storageDelta }) });
-  if (finalOutcome?.terminalVerdict === 'recovery-required') die(finalOutcome.reason);
   console.log(`\n(the above is read back from disk, verified — not a tag lookup)`);
   process.exit(0);
 }
@@ -2005,7 +2130,10 @@ async function main() {
 // guard merely importing this file would start a live update — a network fetch, a directory swap, and
 // a process.exit() inside whatever imported it. (Found exactly that way: the reclaim test's import
 // began racing a real update against the test run.)
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Ships in the brain bundle, where only kb/ modules exist, so it cannot import
+// plugin/scripts/entrypoint.mjs; this is that helper's comparison, inline: real paths on both sides.
+const invokedDirectly = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (invokedDirectly) for (const signal of ['SIGTERM', 'SIGINT']) process.once(signal, () => interruptedBySignal(signal));
 if (invokedDirectly && STAGED_RELEASE_FILE) {
   (async () => {
     const input = JSON.parse(fs.readFileSync(STAGED_RELEASE_FILE, 'utf8'));

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 } : {}) };
 }