ruvnet-brain 4.3.9 → 4.3.10

package/scripts/retrieval-canary.mjs

@@ -2,10 +2,74 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import readline from 'node:readline';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest, validateCoverageLedger } from './coverage-integrity.mjs';
 
+// Both release phases resolve against an explicit installed context, never the checkout.
+export async function resolveInstalledCanaryCitation({ kbDir, matched, expected, passageFileDigests = new Map() }) {
+  if (!path.isAbsolute(kbDir || '')) throw new Error('installed canary KB path must be absolute');
+  if (String(matched?.repo || '').toLowerCase() !== expected.repo || matched?.path !== expected.path) return { resolved: false };
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(expected.repo)) throw new Error('installed citation repository violates containment');
+  const rootStat = fs.lstatSync(kbDir);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || fs.realpathSync(kbDir) !== path.resolve(kbDir)) {
+    throw new Error('installed canary KB root or parent is a symlink; canonical containment required');
+  }
+  const files = [path.join(kbDir, `${expected.repo}.passages.jsonl`), path.join(kbDir, `${expected.repo}.big.passages.jsonl`)]
+    .filter((file) => { try { fs.lstatSync(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } });
+  for (const file of files) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || path.dirname(fs.realpathSync(file)) !== kbDir) {
+      throw new Error('installed citation file is a symlink or violates containment');
+    }
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stream = fs.createReadStream(file, { fd, autoClose: false });
+    const hash = crypto.createHash('sha256');
+    stream.on('data', (bytes) => hash.update(bytes));
+    const rows = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let passageSha256 = null;
+    try {
+      for await (const line of rows) {
+        let record;
+        try { record = JSON.parse(line); } catch { continue; }
+        if (record?.path !== expected.path) continue;
+        if (digest(record) !== expected.passageSha256) continue;
+        const text = record.fullText || record.text;
+        if (typeof text !== 'string' || !text || typeof matched.text !== 'string' || !matched.text.includes(text)) continue;
+        passageSha256 = expected.passageSha256;
+      }
+      const after = fs.lstatSync(file);
+      const opened = fs.fstatSync(fd);
+      if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino
+        || opened.ino !== stat.ino || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs
+        || after.ctimeMs !== stat.ctimeMs) throw new Error('installed citation changed during verification');
+      const passageFileSha256 = hash.digest('hex');
+      passageFileDigests.set(file, passageFileSha256);
+      if (passageSha256) return { resolved: true, evidence: { passageSha256, passageFileSha256,
+        hitContentSha256: crypto.createHash('sha256').update(matched.text).digest('hex') } };
+    } finally {
+      rows.close();
+      await new Promise((resolve, reject) => stream.close((error) => error ? reject(error) : resolve()));
+    }
+  }
+  return { resolved: false };
+}
+
+function expectedSources(expected) {
+  return [{ path: expected.path, passageSha256: expected.passageSha256 }, ...(expected.alternatives || [])];
+}
+function validExpectedSources(expected) {
+  if (!expected || !['passageSha256,path', 'alternatives,passageSha256,path'].includes(Object.keys(expected).sort().join(','))) return false;
+  if (expected.alternatives !== undefined && (!Array.isArray(expected.alternatives)
+    || expected.alternatives.length < 1 || expected.alternatives.length > 8)) return false;
+  const sources = expectedSources(expected);
+  return new Set(sources.map((source) => source?.path)).size === sources.length && sources.every((source) =>
+    source && Object.keys(source).sort().join(',') === 'passageSha256,path'
+    && typeof source.path === 'string' && source.path && !path.isAbsolute(source.path)
+    && !source.path.split(/[\\/]/).includes('..') && HEX64.test(String(source.passageSha256 || '')));
+}
+
 const HEX40 = /^[a-f0-9]{40}$/;
 const HEX64 = /^[a-f0-9]{64}$/;
 
@@ -96,10 +160,7 @@ export function validateRetrievalQueryEvidence(evidence) {
     if (Object.keys(row || {}).sort().join(',') !== 'expected,query,recordSha256'
       || typeof row.query !== 'string' || row.query !== row.query.trim().replace(/\s+/g, ' ')
       || normalized.length < 24 || seenQueries.has(normalized)
-      || !expected || Object.keys(expected).sort().join(',') !== 'passageSha256,path'
-      || typeof expected.path !== 'string' || !expected.path || path.isAbsolute(expected.path)
-      || expected.path.split(/[\\/]/).includes('..')
-      || !HEX64.test(String(expected.passageSha256 || ''))
+      || !validExpectedSources(expected)
       || row.recordSha256 !== digest({ store, query: row.query, expected })) {
       throw new Error(`independent retrieval query evidence for ${store} is malformed`);
     }
@@ -187,7 +248,8 @@ export function validateRetrievalCanaryPlan(plan) {
     throw new Error('oracle denominator differs from eligible coverage');
   }
   if (new Set(ids).size !== ids.length) throw new Error('retrieval canary plan has duplicate case ids');
-  if ((!plan.cases.some(({ cohort }) => cohort === 'delta') && plan.noDelta !== true)
+  const hasDelta = plan.cases.some(({ cohort }) => cohort === 'delta');
+  if ((!hasDelta && plan.noDelta !== true) || (hasDelta && plan.noDelta === true)
     || !plan.cases.some(({ cohort }) => cohort === 'legacy')) {
     throw new Error('retrieval canary plan requires delta and legacy cohorts');
   }
@@ -316,12 +378,15 @@ export function buildRetrievalCanaryPlan({ coverage, baseline, candidate, covera
     if (!strata.has(stratum)) strata.set(stratum, []);
     strata.get(stratum).push(entry);
   });
+  // Source-only releases retain the same corpus sample; the plan still seals exact release bytes.
+  const samplingGeneration = coverage.kind === 'ruvnet-brain-release-coverage'
+    ? coverage.corpusCoverage.coverageGeneration : coverageGeneration;
   const sampleCount = Math.min(legacyPool.length, legacySampleSize ?? Math.max(10, Math.ceil(eligible.length * 0.1)));
   if (sampleCount < strata.size) throw new Error(`legacy sample must cover all ${strata.size} passage-count strata`);
   const selected = [];
   for (const [stratum, entries] of strata) {
-    entries.sort((a, b) => digest(`${coverageGeneration}:${stratum}:${storeOf(a.row)}`)
-      .localeCompare(digest(`${coverageGeneration}:${stratum}:${storeOf(b.row)}`)));
+    entries.sort((a, b) => digest(`${samplingGeneration}:${stratum}:${storeOf(a.row)}`)
+      .localeCompare(digest(`${samplingGeneration}:${stratum}:${storeOf(b.row)}`)));
     selected.push({ ...entries.shift(), stratum });
   }
   while (selected.length < sampleCount) {
@@ -338,9 +403,8 @@ export function buildRetrievalCanaryPlan({ coverage, baseline, candidate, covera
       const store = storeOf(row);
       const observedPassageCount = passageCount ?? passages.get(store).length;
       const evidence = queryEvidence.queries[store];
-      const matches = passages.get(store).filter((row) => row.path === evidence?.expected?.path
-        && digest(row) === evidence.expected.passageSha256);
-      if (!evidence || matches.length !== 1) {
+      if (!evidence || expectedSources(evidence.expected).some((source) =>
+        passages.get(store).filter((row) => row.path === source.path && digest(row) === source.passageSha256).length !== 1)) {
         throw new Error(`${store} has no sealed independent query evidence`);
       }
       return {
@@ -430,10 +494,12 @@ export function validateRetrievalCanaryReceipt(receipt, { plan, requireAcceptanc
   for (const row of receipt.cases) {
     const expected = plan.cases.find(({ id }) => id === row.id)?.expected;
     const ranked = row.retrievalHit ? row.citations?.[row.rank - 1] : null;
+    const accepted = expectedSources(expected).find((source) => source.path === ranked?.path);
     if (row.retrievalHit && (String(ranked?.repo || '').toLowerCase() !== expected.repo
-      || ranked?.path !== expected.path
-      || (row.citationResolved === true && (row.citationEvidence?.passageSha256 !== expected.passageSha256
-        || !HEX64.test(String(row.citationEvidence?.passageFileSha256 || '')))))) {
+      || !accepted
+      || (row.citationResolved === true && (row.citationEvidence?.passageSha256 !== accepted.passageSha256
+        || !HEX64.test(String(row.citationEvidence?.passageFileSha256 || ''))
+        || (ranked.contentSha256 !== undefined && row.citationEvidence?.hitContentSha256 !== ranked.contentSha256))))) {
       throw new Error(`retrieval canary ${row.id} hit or citation evidence differs from the sealed plan`);
     }
   }
@@ -448,7 +514,9 @@ export function validateRetrievalCanaryReceipt(receipt, { plan, requireAcceptanc
     deltaHits: delta.filter(({ retrievalHit }) => retrievalHit === true).length,
     deltaCitations: delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length,
     recallAt10: hits / receipt.cases.length,
-    deltaCitationRate: delta.length ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length : 0,
+    deltaCitationRate: delta.length
+      ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length
+      : plan.noDelta === true ? 1 : 0,
     unknown,
     skipped,
   };
@@ -478,12 +546,14 @@ export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, ca
         const rows = resultRows(await search({ query: canary.query, k: 10 }));
         const top = rows.slice(0, 10);
         const rank = top.findIndex((row) => String(row?.repo || '').toLowerCase() === canary.expected.repo
-          && row?.path === canary.expected.path);
+          && expectedSources(canary.expected).some((source) => row?.path === source.path));
         const matched = rank >= 0 ? top[rank] : null;
-        const resolved = matched ? await citationResolver(matched, canary.expected) : { resolved: false };
+        const accepted = matched ? expectedSources(canary.expected).find((source) => source.path === matched.path) : null;
+        const resolved = matched ? await citationResolver(matched, { repo: canary.expected.repo, ...accepted }) : { resolved: false };
         cases[index] = { id: canary.id, cohort: canary.cohort, status: 'COMPLETED', retrievalHit: rank >= 0,
           citationResolved: resolved?.resolved === true, citationEvidence: resolved?.evidence || null,
-          rank: rank >= 0 ? rank + 1 : null, citations: top.map(({ repo, path: hitPath }) => ({ repo, path: hitPath })) };
+          rank: rank >= 0 ? rank + 1 : null, citations: top.map(({ repo, path: hitPath, contentSha256 }) => ({ repo, path: hitPath,
+            ...(contentSha256 ? { contentSha256 } : {}) })) };
       } catch (error) {
         cases[index] = { id: canary.id, cohort: canary.cohort, status: 'UNKNOWN', retrievalHit: false,
           citationResolved: false, citationEvidence: null, rank: null, citations: [], error: error.message };
@@ -494,7 +564,10 @@ export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, ca
   const hits = cases.filter(({ retrievalHit }) => retrievalHit).length;
   const metrics = { total: cases.length, hits, deltaTotal: delta.length, deltaHits: delta.filter(({ retrievalHit }) => retrievalHit).length,
     deltaCitations: delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length,
-    recallAt10: hits / cases.length, deltaCitationRate: delta.length ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length / delta.length : 0,
+    recallAt10: hits / cases.length,
+    deltaCitationRate: delta.length
+      ? delta.filter(({ retrievalHit, citationResolved }) => retrievalHit && citationResolved).length / delta.length
+      : plan.noDelta === true ? 1 : 0,
     unknown: cases.filter(({ status }) => status === 'UNKNOWN').length,
     skipped: cases.filter(({ status }) => status === 'SKIPPED').length };
   const payload = { schemaVersion: 1, kind: 'ruvnet-brain-retrieval-canary-receipt', sourceSha, artifactSha256,

package/scripts/selfcheck.mjs

@@ -477,7 +477,7 @@ export function assertContract({ rec, measurement, mode, timeoutSec }) {
 }
 
 // ── §4 THE BATTERY: every installed registration × every stdin regime ───────────────────────────
-export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, surface = null, env = {} } = {}) {
+export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, surface = null, env = {}, inspectOnly = false } = {}) {
   const reg = await loadRegistry();
   const s = surface ?? resolveInstalledSurface({ home, repo });
   if (!s.ok) return { ok: false, reason: s.reason, violations: [], results: [] };
@@ -487,6 +487,7 @@ export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tm
   const { contracts } = reg.loadContracts(s.root);
 
   const registrations = readInstalledRegistrations(s.hooksFile);
+  if (inspectOnly) return { ok: true, surface: s, registrations, violations: [], results: [] };
   const violations = [];
   const results = [];
 
@@ -614,13 +615,20 @@ export async function selfCheck({ home = os.homedir(), repo = null, cwd = os.tmp
   }
 
   // (b) THE BATTERY
-  const battery = await runBattery({ home, repo, cwd, regimes });
+  const battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
   if (!battery.ok) {
     lines.push(`hooks: ${battery.reason}`);
     violations.push({ kind: 'no-plugin', where: 'hooks', detail: battery.reason });
   } else {
     violations.push(...battery.violations);
-    lines.push(`hooks: ${battery.registrations.length} registrations from ${battery.surface.source}, ${regimes.length} stdin regimes each (${battery.results.length} firings)`);
+    if (battery.registrations.length !== 0) {
+      violations.push({
+        kind: 'automatic-registration',
+        where: battery.surface.source,
+        detail: `${battery.registrations.length} retired Brain lifecycle registration(s) remain installed`,
+      });
+    }
+    lines.push(`hooks: ${battery.registrations.length} automatic registrations from ${battery.surface.source}; zero is the required retired state`);
   }
 
   // (c) COEXISTENCE — reported, never charged to the user
@@ -656,7 +664,7 @@ export function formatVerdict(result, { color = null } = {}) {
   const out = [];
   for (const l of result.lines) out.push(`  ${c.dim(l)}`);
   if (!result.violations.length) {
-    out.push(`  ${c.green('✓ Self-check passed.')} Every shipped hook answered inside its contract on this machine.`);
+    out.push(`  ${c.green('✓ Self-check passed.')} The installed Brain surface has zero automatic lifecycle registrations.`);
     return out.join('\n');
   }
   out.push(`  ${c.red(`✗ Self-check FAILED — ${result.violations.length} contract violation(s):`)}`);

package/scripts/snapshot-freshness.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * snapshot-freshness.mjs — "a claimed backup is not a found backup" as a shared, pure function.
+ *
+ * `distill-project.mjs` established this discipline (PR #192): `ruflo memory backup` exiting 0
+ * proves nothing about whether a NEW file actually landed — a stale snapshot from a prior run
+ * sitting in the same directory is otherwise indistinguishable from a genuine fresh one, and a
+ * caller that trusts the exit code alone can proceed to mutate state on a false undo guarantee.
+ * Extracted here so `health-repair.mjs`'s fleet distillation (a second, independent caller of
+ * `ruflo memory backup` per store) can share the exact same proof instead of re-deriving it —
+ * duplicating this logic once already cost a real, shipped defect (see the 2026-08-29 Dream Cycle
+ * report, "Next steps #1").
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Some filesystems truncate mtime to whole seconds (FAT32, some overlay/network mounts), so a file
+// written a moment after `sinceMs` was captured can still report an mtime slightly before it. This
+// grace window is tolerance for that truncation, not a loophole — it stays far smaller than the gap
+// between one run and the next.
+export const MTIME_GRACE_MS = 1500;
+
+/**
+ * The newest matching snapshot file in `dir`, or null. With `sinceMs`, only a file whose mtime is
+ * no older than that moment (minus the grace window) counts. Mutating callers also provide a
+ * pre-backup inventory, so an unchanged prior snapshot cannot count within that grace. Callers that
+ * legitimately want the newest snapshot ever (e.g. a restore path) pass no `sinceMs`.
+ */
+export function snapshotInventory(dir) {
+  let root;
+  try { root = fs.lstatSync(dir); }
+  catch (error) { if (error.code === 'ENOENT') return new Map(); throw error; }
+  if (!root.isDirectory() || root.isSymbolicLink()) throw new Error('Backup destination is not a regular directory');
+  const inventory = new Map();
+  for (const name of fs.readdirSync(dir)) {
+    if (!/\.(db|sqlite|bak)$/i.test(name) && !/memory.*\d/.test(name)) continue;
+    const file = path.join(dir, name);
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || !stat.size) continue;
+      inventory.set(file, {
+        path: file, mtimeMs: stat.mtimeMs,
+        identity: [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(':'),
+      });
+    } catch { /* a disappearing candidate is not a located backup */ }
+  }
+  return inventory;
+}
+
+export function newestSnapshot(dir, sinceMs = 0, graceMs = MTIME_GRACE_MS, before = null) {
+  try {
+    const files = [...snapshotInventory(dir).values()]
+      .filter(file => file.mtimeMs >= sinceMs - graceMs
+        && (!before || before.get(file.path)?.identity !== file.identity))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return files[0]?.path ?? null;
+  } catch { return null; }
+}

package/scripts/stack-sync.mjs

@@ -186,13 +186,15 @@ export function listInstalledPlugins(pluginsDir = PLUGINS_DIR) {
     // not equality" discipline as the rest of this file. Fall back to the manifest's own version field
     // if the on-disk plugin.json is unreadable, so a present plugin is NEVER reported "not installed".
     let installed = null;
+    const instances = [];
     for (const rec of Array.isArray(records) ? records : []) {
       const v = (rec && rec.installPath ? pluginVersion(rec.installPath) : null)
         || (rec && rec.version && rec.version !== 'unknown' ? rec.version : null);
+      instances.push({ scope: rec?.scope || 'unknown', installPath: rec?.installPath || null, version: v, readable: Boolean(rec?.installPath && pluginVersion(rec.installPath)) });
       if (!v) continue;
       if (installed === null || cmpVersion(v, installed) > 0) installed = v;
     }
-    out.push({ name, installed, source: 'plugin', marketplace });
+    out.push({ name, installed, source: 'plugin', marketplace, instances });
   }
   return out;
 }
@@ -209,15 +211,8 @@ function listInstalled({ lib = GLOBAL_LIB, pluginsDir = PLUGINS_DIR } = {}) {
     }
   };
   scan(lib);
-  // Merge in plugin-sourced tools (ISSUE #22). Dedup by name: a tool present BOTH globally and as a
-  // plugin appears once, and the global-npm copy wins — it is the one classify() can compare against
-  // npm dist-tags. A plugin-only tool is added, so it can never be reported "not installed".
-  const seen = new Set(out.map((r) => r.name));
-  for (const p of listInstalledPlugins(pluginsDir)) {
-    if (seen.has(p.name)) continue;
-    seen.add(p.name);
-    out.push(p);
-  }
+  // Preserve both distribution sources; one must not hide the other.
+  out.push(...listInstalledPlugins(pluginsDir));
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
@@ -258,14 +253,9 @@ export function findShadows(npxCache = NPX_CACHE, lib = GLOBAL_LIB) {
 // exits) share ONE classification, never two that can drift.
 export function classify(pkgs) {
   return pkgs.map((p) => {
-    // ISSUE #22 — a Claude Code plugin tracks ITS MARKETPLACE's update cadence, not npm semver. There
-    // is no npm dist-tag oracle for it (querying `npm view <plugin>` would compare against an unrelated
-    // package or 404), so we do not manufacture a drift signal. It is present and installed ⇒ CURRENT;
-    // a plugin is only BROKEN if we could not read any version at all. Either way it is COUNTED and is
-    // never reported "not installed". This also keeps the npm-registry "blind tool" guard scoped to
-    // real npm rows (see audit()/auditModel()).
+    // Installed records prove presence, not marketplace currency.
     if (p.source === 'plugin') {
-      return { ...p, tag: 'plugin', target: p.installed, state: p.installed ? 'CURRENT' : 'BROKEN' };
+      return { ...p, tag: 'plugin', target: null, state: p.installed ? 'INSTALLED_UNVERIFIED' : 'BROKEN', evidence: 'local install record only; marketplace revision not checked' };
     }
     const want = TAG_POLICY[p.name] || DEFAULT_TAG;
     const tags = registryTags(p.name);
@@ -293,9 +283,7 @@ function audit() {
   // inside the fix for it. Silence is not health.
   const rows = classify(pkgs);
   const unresolved = rows.filter((r) => r.state === 'UNRESOLVED');
-  // Guard scoped to npm rows (ISSUE #22): plugin rows are CURRENT by construction, so counting them
-  // here would let a fully-unreachable registry hide behind a couple of installed plugins — the exact
-  // "blind tool reports health" bug this guard exists to kill, reintroduced. Denominator = npm rows.
+  // Registry reachability is measured only against npm rows; plugins remain unverified.
   const npmRows = rows.filter((r) => r.source !== 'plugin');
   if (npmRows.length && unresolved.length === npmRows.length) {
     die(`could not reach the npm registry for ANY of ${npmRows.length} npm packages.\n` +
@@ -303,7 +291,7 @@ function audit() {
   }
 
   const shadows = findShadows();
-  return { rows, unresolved, shadows, stale: shadows.filter((s) => s.global && s.version !== s.global) };
+  return { rows, unresolved, shadows, stale: shadows.filter((s) => s.global && isBehind(s.version, s.global)) };
 }
 
 // Non-exiting audit for embedders (the Onboarding Console). Same measurement as audit(), but returns
@@ -316,32 +304,44 @@ export function auditModel() {
   const rows = classify(pkgs);
   const unresolved = rows.filter((r) => r.state === 'UNRESOLVED');
   const shadows = findShadows();
-  const stale = shadows.filter((s) => s.global && s.version !== s.global);
+  const stale = shadows.filter((s) => s.global && isBehind(s.version, s.global));
   // Same npm-scoped guard as audit() (ISSUE #22): plugin rows never count toward "registry unreachable".
   const npmRows = rows.filter((r) => r.source !== 'plugin');
   const error = npmRows.length && unresolved.length === npmRows.length
     ? `could not reach the npm registry for any of ${npmRows.length} npm packages` : null;
-  return { rows, unresolved, shadows, stale, error };
+  return { rows, unresolved, shadows, stale, error, summary: summarizeAudit({ rows, shadows }) };
+}
+
+export function summarizeAudit({ rows, shadows }) {
+  const count = (state) => rows.filter((row) => row.state === state).length;
+  const summary = { behind: count('BEHIND'), broken: count('BROKEN'),
+    unverified: count('INSTALLED_UNVERIFIED') + count('UNRESOLVED'), shadows: shadows.length,
+    stale: shadows.filter((s) => s.global && isBehind(s.version, s.global)).length };
+  summary.verdict = summary.behind || summary.broken || summary.shadows ? 'DRIFT'
+    : summary.unverified || !rows.length ? 'UNKNOWN' : 'PASS';
+  summary.exitCode = summary.verdict === 'PASS' ? 0 : summary.verdict === 'UNKNOWN' ? 4 : 1;
+  return summary;
 }
 
 function report({ rows, shadows, stale }) {
-  const w = Math.max(...rows.map((r) => r.name.length));
+  const w = Math.max(1, ...rows.map((r) => r.name.length));
   const nPlugin = rows.filter((r) => r.source === 'plugin').length;
   const nNpm = rows.length - nPlugin;
-  log(`\n  RuvNet stack — ${rows.length} packages (${nNpm} npm-global, ${nPlugin} Claude Code plugin)\n`);
+  log(`\n  RuvNet stack — ${rows.length} distribution records (${nNpm} npm-global, ${nPlugin} Claude Code plugin)\n`);
   for (const r of rows) {
-    const mark = { CURRENT: '  ok  ', BEHIND: 'BEHIND', AHEAD: ' ahead', BROKEN: 'BROKEN', UNRESOLVED: '  ??  ' }[r.state];
+    const mark = { CURRENT: '  ok  ', BEHIND: 'BEHIND', AHEAD: ' ahead', BROKEN: 'BROKEN', UNRESOLVED: '  ??  ', INSTALLED_UNVERIFIED: 'UNVERIFIED' }[r.state];
     const detail = r.state === 'BEHIND' ? `${r.installed} -> ${r.target}  (@${r.tag})`
       : r.state === 'AHEAD' ? `${r.installed}  (ahead of @${r.tag} ${r.target} — alpha track; left alone)`
       : r.state === 'BROKEN' ? `no readable version on disk; registry has ${r.target ?? '?'}`
-      : r.source === 'plugin' ? `${r.installed}  (plugin · ${r.marketplace} marketplace)`
+      : r.source === 'plugin' ? `${r.installed}  (plugin · ${r.marketplace}; marketplace currency NOT CHECKED; ${r.instances?.length || 1} scope record(s))`
       : r.installed;
     log(`  [${mark}] ${r.name.padEnd(w)}  ${detail}`);
+    if (r.instances?.length > 1) for (const instance of r.instances) log(`      ${instance.scope}: ${instance.version || 'UNREADABLE'} (${instance.readable ? 'disk' : 'record only'})`);
   }
   if (shadows.length) {
     log(`\n  npx shadow copies:`);
     for (const s of shadows) {
-      log(`    ${s.name}@${s.version}${s.global && s.version !== s.global ? `   STALE — global is ${s.global}` : ''}`);
+      log(`    ${s.name}@${s.version}${s.global && isBehind(s.version, s.global) ? `   STALE — global is ${s.global}` : ''}`);
     }
   }
   log('');
@@ -391,8 +391,9 @@ function sync({ dryRun = false } = {}) {
   const toInstall = [...behind, ...broken.filter((r) => r.target)].map((r) => `${r.name}@${r.target}`);
 
   if (!toInstall.length && !stale.length) {
-    log('  one copy of everything, all current, no shadows. Nothing to do.');
-    writeReceipt(a, [], []);
+    log(`  No npm repair selected. Audit: ${JSON.stringify(summarizeAudit(a))}`);
+    if (!dryRun) writeReceipt(a, [], []);
+    process.exitCode = summarizeAudit(a).exitCode;
     return;
   }
   if (dryRun) {
@@ -431,7 +432,10 @@ function sync({ dryRun = false } = {}) {
   }
   if (wrong.length) die(`npm reported success but THE DISK DISAGREES:\n   - ${wrong.join('\n   - ')}`);
 
-  writeReceipt(audit(), toInstall, purged);
+  const after = audit();
+  writeReceipt(after, toInstall, purged);
+  process.exitCode = summarizeAudit(after).exitCode;
+  log(`  Remaining audit: ${JSON.stringify(summarizeAudit(after))}`);
   log(`\n  synced ${toInstall.length} package(s); purged ${purged.length} shadow(s); verified against disk.`);
 }
 
@@ -440,18 +444,12 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('stack-sync.mjs'))
   const args = process.argv.slice(2);
   if (args.includes('--audit')) {
     const a = audit();
-    const { behind, broken, stale } = report(a);
-    // UNRESOLVED counts as drift, not as health: a package we could not measure is a package we
-    // cannot vouch for. Reporting "current" for something we never checked is the lie this tool exists to stop.
-    const unres = a.unresolved.length;
-    const bad = behind.length + broken.length + stale.length + unres;
-    if (bad) {
-      log(`  DRIFT: ${behind.length} behind, ${broken.length} broken, ${stale.length} stale shadow(s)` +
-          (unres ? `, ${unres} UNMEASURED (registry unreachable)` : '') + '.');
-      log(`  Fix:   node scripts/stack-sync.mjs --sync\n`);
-      process.exit(1); // non-zero: a watchdog must never call a drifted stack "green"
-    }
-    log('  one copy of everything, all current, no shadows.\n');
+    report(a);
+    const summary = summarizeAudit(a);
+    log(`  Audit: ${JSON.stringify(summary)}`);
+    if (summary.unverified) log('  Required: verify each plugin against its marketplace revision and each unresolved npm target against registry tags.');
+    if (summary.shadows) log('  Cached copies are present; inspect invocation paths before removing any cache. No copies removed by audit.');
+    process.exitCode = summary.exitCode;
   } else if (args.includes('--sync')) {
     sync({ dryRun: args.includes('--dry-run') });
   } else {

package/scripts/staged-host-verifier.mjs

@@ -4,8 +4,48 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { runHostMatrixAsync } from './host-install-matrix.mjs';
+import { validatePlanAgainstCoverage } from './retrieval-canary.mjs';
+import { extractZip } from '../kb/zip-extract.mjs';
+import { tarExtractionInvocation } from './publication-receipt.mjs';
 
 const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+export function readCandidateRetrieval({ manifest, planFile, coverageFile }) {
+  if (!planFile || !coverageFile) throw new Error('candidate retrieval requires sealed plan and coverage files');
+  const plan = JSON.parse(fs.readFileSync(planFile));
+  const coverageBytes = fs.readFileSync(coverageFile);
+  const coverage = JSON.parse(coverageBytes);
+  // An observed baseline defines the delta only; it never supplies candidate PASS evidence.
+  validatePlanAgainstCoverage(plan, coverage, { allowObservedBaseline: true });
+  const npm = manifest.members?.filter(({ role }) => role === 'npm') || [];
+  const bundle = manifest.members?.filter(({ role }) => role === 'bundle') || [];
+  const coverageSha256 = crypto.createHash('sha256').update(coverageBytes).digest('hex');
+  if (npm.length !== 1 || bundle.length !== 1
+    || plan.candidate.sourceSha !== manifest.candidateSha
+    || plan.candidate.packageSha256 !== npm[0].sha256 || plan.candidate.archiveSha256 !== bundle[0].sha256
+    || plan.coverage.sha256 !== coverageSha256 || plan.candidate.coverageSha256 !== coverageSha256
+    || plan.coverage.bytes !== coverageBytes.length
+    || coverage.releaseIdentity?.sourceSnapshot !== manifest.candidateSha
+    || coverage.releaseIdentity?.version !== manifest.version || coverage.releaseIdentity?.tag !== manifest.tag
+    || plan.candidate.publicLedgerSha256 !== coverage.generationLedger?.sha256
+    || plan.candidate.publicLedgerBytes !== coverage.generationLedger?.bytes
+    || plan.candidate.publicStoreCount !== coverage.generationLedger?.storeCount
+    || plan.candidate.publicInventoryPartitionSha256 !== coverage.publicInventoryPartitionSha256) {
+    throw new Error('candidate retrieval plan, coverage or artifact identity mismatch');
+  }
+  return { plan, sourceSha: manifest.candidateSha, artifactSha256: npm[0].sha256,
+    candidateArchiveSha256: bundle[0].sha256, packageBytes: npm[0].size, bundleBytes: bundle[0].size };
+}
+
+export function verifyCandidateRetrievalAssets({ retrieval, assets }) {
+  for (const [file, digest, bytes] of [[assets.packagePath, retrieval.artifactSha256, retrieval.packageBytes],
+    [assets.bundlePath, retrieval.candidateArchiveSha256, retrieval.bundleBytes]]) {
+    if (!Number.isSafeInteger(bytes) || bytes < 1 || fs.statSync(file).size !== bytes || sha256(file) !== digest) {
+      throw new Error(`candidate artifact does not match sealed retrieval input: ${file}`);
+    }
+  }
+  return true;
+}
 const locate = (name) => {
   try { return execFileSync('which', [name], { encoding: 'utf8' }).trim(); } catch { return null; }
 };
@@ -23,25 +63,32 @@ const run = (name, args, options) => {
 // tests/unit/staged-host-verifier.test.mjs pins it, but it is now an alias, not a second copy.
 export { classifyDoctor as classifyDoctorResult } from './host-install-matrix.mjs';
 
-const preparePackage = ({ packagePath, bundlePath }) => {
+const preparePackage = async ({ packagePath, bundlePath }) => {
   const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-staged-host-'));
-  run('tar', ['-xzf', packagePath, '-C', temp]);
-  const packageRoot = path.join(temp, 'package');
-  const bundleRoot = path.join(packageRoot, 'dist', 'ruvnet-brain');
-  fs.mkdirSync(bundleRoot, { recursive: true });
-  run('unzip', ['-q', bundlePath, '-d', bundleRoot]);
-  const nested = path.join(bundleRoot, 'ruvnet-brain');
-  if (fs.existsSync(nested)) {
-    for (const name of fs.readdirSync(nested)) fs.renameSync(path.join(nested, name), path.join(bundleRoot, name));
-    fs.rmdirSync(nested);
+  try {
+    const extraction = tarExtractionInvocation(packagePath, temp);
+    run('tar', extraction.args, { cwd: extraction.cwd });
+    const packageRoot = path.join(temp, 'package');
+    const bundleRoot = path.join(packageRoot, 'dist', 'ruvnet-brain');
+    fs.mkdirSync(bundleRoot, { recursive: true });
+    await extractZip(bundlePath, bundleRoot);
+    const nested = path.join(bundleRoot, 'ruvnet-brain');
+    if (fs.existsSync(nested)) {
+      for (const name of fs.readdirSync(nested)) fs.renameSync(path.join(nested, name), path.join(bundleRoot, name));
+      fs.rmdirSync(nested);
+    }
+    return { temp, packageRoot };
+  } catch (error) {
+    fs.rmSync(temp, { recursive: true, force: true });
+    throw error;
   }
-  return { temp, packageRoot };
 };
 
-export function stagedHostVerifier({ assets, identity }) {
+export function stagedHostVerifier({ assets, identity, retrieval }, { runMatrix = runHostMatrixAsync } = {}) {
   return {
     async verify({ source, assets: observedAssets = assets }) {
-      const prepared = preparePackage(observedAssets);
+      if (retrieval) verifyCandidateRetrievalAssets({ retrieval, assets: observedAssets });
+      const prepared = await preparePackage(observedAssets);
       try {
         // The loop, the mode names, the env and the doctor verdict all live in
         // scripts/host-install-matrix.mjs, shared with the published-side check in
@@ -50,13 +97,15 @@ export function stagedHostVerifier({ assets, identity }) {
         // install shape than the one that runs after publication — so the two halves of a release
         // were judging different things and could not be compared. Only the STAGED-vs-PUBLISHED
         // difference is real, and it is now a named variant rather than a second implementation.
-        const matrix = await runHostMatrixAsync({
+        const matrix = await runMatrix({
           packageRoot: prepared.packageRoot,
           version: identity.version,
           variant: 'staged',
           locate,
           temp: prepared.temp,
+          retrieval,
         });
+        if (retrieval) verifyCandidateRetrievalAssets({ retrieval, assets: observedAssets });
         if (matrix.verdict !== 'PASS') {
           return { verdict: 'FAIL', source, error: matrix.error, fixtures: matrix.fixtures };
         }