ruvnet-brain 4.3.40 → 4.4.1

package/scripts/console-instances.mjs

@@ -0,0 +1,203 @@
+// console-instances.mjs — the installer's view of running Consoles: which receipts are real, and how
+// to replace an owned Console that is still serving a pre-update runtime without asking anyone.
+//
+// Two owner-Mac failures (2026-09-30) this exists for:
+//  1. Receipts left by Consoles that had long since died (2026-09-16/17) were counted as "stale
+//     running" forever, so --doctor said pending-console-restart / FAILING with nothing to restart.
+//     A receipt whose pid is gone AND whose port does not answer /api/runtime with the receipt's
+//     own identity is debris: it is pruned.
+//  2. After a successful --update the installer told the owner to "restart Console". The Console
+//     already knows how to replace an owned stale instance of itself (scripts/onboarding-console.mjs
+//     launchConsole, state 'stale-running': token-authenticated shutdown, then serve on the same
+//     port). The installer now runs exactly that, from the freshly activated runtime, without --open.
+//
+// Everything here is synchronous because syncHostsAfterUpdate is; the one network probe runs in a
+// bounded child node process.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+const PRODUCT = 'ruvnet-brain-console';
+// The same identity fields onboarding-console.mjs sameRuntimeIdentity compares.
+const IDENTITY_KEYS = ['product', 'schema', 'apiContract', 'pid', 'port', 'startedAt', 'scope',
+  'scriptRealpath', 'runtimeVersion', 'sourceSha256'];
+
+export function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code !== 'ESRCH'; } // EPERM: alive, owned by someone else
+}
+
+/** GET 127.0.0.1:<port>/api/runtime → parsed JSON, or null. Bounded; never throws. */
+export function probeRuntimeSync(port, timeoutMs = 1500) {
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  const code = `const h=require('node:http');const r=h.get({host:'127.0.0.1',port:${port},path:'/api/runtime',timeout:${timeoutMs}},(s)=>{let b='';s.on('data',(c)=>{b+=c;});s.on('end',()=>{if(s.statusCode===200)process.stdout.write(b);process.exit(0);});});r.on('error',()=>process.exit(0));r.on('timeout',()=>{r.destroy();process.exit(0);});`;
+  const run = spawnSync(process.execPath, ['-e', code], { encoding: 'utf8', timeout: timeoutMs + 1000, windowsHide: true });
+  try { return run.stdout ? JSON.parse(run.stdout) : null; } catch { return null; }
+}
+
+export const sameIdentity = (left, right) => IDENTITY_KEYS.every((key) => left?.[key] === right?.[key]);
+
+const MONTHS = 'JanFebMarAprMayJunJulAugSepOctNovDec';
+/** When process `pid` started (epoch ms, UTC, 1 s resolution), or null when it cannot be read. */
+let clockTicks = null;
+/**
+ * Linux: boot-relative start (/proc/<pid>/stat field 22, clock ticks since boot) anchored at the kernel's
+ * boot time (/proc/stat btime) — not `ps lstart`, which a forward wall-clock jump would push later.
+ */
+export function linuxProcessStartMs(pid, { readFile = fs.readFileSync, spawn = spawnSync } = {}) {
+  try {
+    const stat = String(readFile(`/proc/${pid}/stat`, 'utf8'));
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' '); // field 3 onward (comm may hold spaces)
+    const startTicks = Number(fields[22 - 3]);
+    const btime = Number(String(readFile('/proc/stat', 'utf8')).match(/^btime\s+(\d+)/m)?.[1]);
+    if (clockTicks === null) clockTicks = Number(String(spawn('getconf', ['CLK_TCK'], { encoding: 'utf8' })?.stdout || '').trim()) || 100;
+    if (!Number.isFinite(startTicks) || !Number.isFinite(btime)) return null;
+    return btime * 1000 + Math.round((startTicks * 1000) / clockTicks);
+  } catch { return null; }
+}
+
+export function processStartMs(pid, { spawn = spawnSync, platform = process.platform, readFile } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (platform === 'linux') {
+    const linux = linuxProcessStartMs(pid, { spawn, ...(readFile ? { readFile } : {}) });
+    if (linux !== null) return linux;
+  }
+  const run = process.platform === 'win32'
+    ? spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      `$p=Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().ToString('ddd MMM d HH:mm:ss yyyy',[Globalization.CultureInfo]::InvariantCulture)`],
+    { encoding: 'utf8', windowsHide: true })
+    : spawn('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' } });
+  if (run?.status !== 0) return null;
+  const m = String(run.stdout || '').trim().match(/^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/);
+  if (!m || MONTHS.indexOf(m[1]) % 3 !== 0) return null;
+  return Date.UTC(+m[6], MONTHS.indexOf(m[1]) / 3, +m[2], +m[3], +m[4], +m[5]);
+}
+
+/**
+ * A live pid that is NOT the receipt's Console: the process now holding that pid started after the
+ * Console wrote its receipt (a Console's process always starts before it records startedAt). Two seconds
+ * of slack cover the 1 s resolution of the start time. Unreadable start time = not provably reused.
+ */
+export function pidReused(receipt, { startMs = processStartMs } = {}) {
+  const recorded = Date.parse(receipt?.startedAt || '');
+  const started = startMs(receipt?.pid);
+  return Number.isFinite(recorded) && Number.isFinite(started) && started > recorded + 2_000;
+}
+
+/**
+ * Console receipts in `receiptDir`, with dead ones pruned. A receipt is dead when its port does not
+ * answer /api/runtime with the receipt's identity AND either its pid is not alive or that pid now
+ * belongs to a process that started after the receipt was written (pid reuse). A busy live Console
+ * (pid alive, same process) is never pruned. A receipt with no integer pid cannot be proven dead.
+ */
+export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = probeRuntimeSync, startMs = processStartMs } = {}) {
+  const live = [];
+  const pruned = [];
+  let names = [];
+  try { names = fs.readdirSync(receiptDir).filter((name) => name.endsWith('.json')); }
+  catch { return { live, pruned }; } // no receipt directory is the ordinary "no Console" state
+  for (const name of names) {
+    const file = path.join(receiptDir, name);
+    let receipt;
+    try { receipt = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
+    if (receipt?.product !== PRODUCT || receipt.schema !== 1) continue;
+    if (Number.isInteger(receipt.pid) && receipt.pid > 0) {
+      const dead = !alive(receipt.pid);
+      const reused = !dead && pidReused(receipt, { startMs });
+      if (dead || reused) {
+        const answer = probe(receipt.port);
+        if (!answer || !sameIdentity(answer, receipt)) {
+          try { fs.unlinkSync(file); } catch { /* raced or read-only: still not a running Console */ }
+          pruned.push({ file, pid: receipt.pid, port: receipt.port ?? null, startedAt: receipt.startedAt ?? null,
+            reason: dead ? 'pid not alive' : 'pid reused by a process started after the receipt' });
+          continue;
+        }
+      }
+    }
+    live.push({ file, receipt });
+  }
+  return { live, pruned };
+}
+
+// The replacement Console is a user-facing process, not part of the installer run. It inherits the
+// user's environment — provider API keys (ANTHROPIC/OPENAI/OPENROUTER/GEMINI/GOOGLE/XAI) the Console reads,
+// HTTP(S)_PROXY / NO_PROXY / NODE_EXTRA_CA_CERTS its release fetch needs — minus the flags that describe
+// THIS run: the scheduler's nightly identity, test-harness switches, the refresh-run lock token, Node/npm
+// process plumbing. A denylist, so nothing the Console legitimately reads is silently lost.
+const CONSOLE_ENV_DENY = new Set(['RUVNET_NIGHTLY', 'RUVNET_BRAIN_TEST', 'RUVNET_BRAIN_TEST_LATEST_TAG', 'RUVNET_BRAIN_SCHEDULER_TEST',
+  'RUVNET_BRAIN_IMPORT_ONLY', 'RUVNET_BRAIN_NO_UPDATE_FALLBACK', 'RUVNET_STRICT_INSTALL', 'RUVNET_REFRESH_RUN_TOKEN',
+  'RUVNET_REFRESH_RECEIPT', 'RUVNET_UPGRADE_NOTICE_FILE', 'NODE_OPTIONS', 'NODE_TEST_CONTEXT', 'INIT_CWD', 'CONSOLE_PORT',
+  // The launching host session's own identity (the spine version it booted, the hook host, its Node).
+  'RUVNET_BRAIN_ACTIVE_VERSION', 'RUVNET_HOOK_HOST', 'RUVNET_NODE_BIN']);
+// CLAUDE* describes the Claude Code SESSION that ran the installer (CLAUDECODE, CLAUDE_PROJECT_DIR,
+// CLAUDE_PLUGIN_ROOT, CLAUDE_SESSION_ID, CLAUDE_CODE_*): stale for a long-lived Console. CLAUDE_CONFIG_DIR
+// is the user's configuration location, not session state, and is kept (host-update.mjs forwards it too).
+const CONSOLE_ENV_DENY_PREFIX = /^(?:RUVNET_NIGHTLY_|npm_|VITEST|CLAUDE(?!_CONFIG_DIR$))/;
+export function consoleEnv(env = process.env, port) {
+  const clean = Object.fromEntries(Object.entries(env).filter(([key, value]) => value != null
+    && !CONSOLE_ENV_DENY.has(key) && !CONSOLE_ENV_DENY_PREFIX.test(key)));
+  return { ...clean, CONSOLE_PORT: String(port) };
+}
+
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+
+/**
+ * Replace every owned Console still serving an older runtime by running the activated runtime's own
+ * launcher (`<entry> --serve`, never --open) in that Console's scope on that Console's port. The
+ * launcher authenticates the shutdown with the private control token from the receipt; we only start
+ * it and wait for the receipt to name the new runtime. Returns one result per stale receipt, each
+ * with `replaced` and, when false, the exact reason.
+ */
+export function replaceStaleConsoles({ entry, identity, receiptDir, env = process.env, timeoutMs = 20_000,
+  spawnFn = spawn, alive = pidAlive, probe = probeRuntimeSync } = {}) {
+  const results = [];
+  const { live } = readConsoleReceipts(receiptDir, { alive, probe });
+  for (const { file, receipt } of live) {
+    if (receipt.sourceSha256 === identity.sourceSha256) continue;
+    const where = { scope: receipt.scope ?? null, port: receipt.port ?? null, pid: receipt.pid ?? null };
+    const refuse = (reason) => results.push({ ...where, replaced: false, reason });
+    if (!Number.isInteger(receipt.pid) || !Number.isInteger(receipt.port) || typeof receipt.scope !== 'string') {
+      refuse('its receipt has no pid/port/scope, so it cannot be addressed safely'); continue;
+    }
+    if (!/^[a-f0-9]{48}$/.test(receipt.controlToken || '')) {
+      refuse('its receipt carries no control token, so the installer cannot prove it owns that Console'); continue;
+    }
+    if (!fs.existsSync(entry)) { refuse(`the activated Console runtime is missing (${entry})`); continue; }
+    if (!fs.existsSync(receipt.scope)) { refuse(`its project directory no longer exists (${receipt.scope})`); continue; }
+    // The pid is alive (dead ones were pruned by readConsoleReceipts). If its port does not answer with
+    // this receipt's identity, it is either a busy Console or a reused pid — we cannot tell which, so we
+    // never delete the receipt (that could orphan a live stale Console). Report it at once instead of
+    // launching and waiting 20s for a process that may never release anything.
+    const answer = probe(receipt.port) || probe(receipt.port);
+    if (!answer || !sameIdentity(answer, receipt)) {
+      refuse(`pid ${receipt.pid} is alive but port ${receipt.port} does not answer with that Console's identity (busy, or the pid was reused); its receipt was kept — restart Console`);
+      continue;
+    }
+    try {
+      const child = spawnFn(process.execPath, [entry, '--serve'], { cwd: receipt.scope, detached: true, stdio: 'ignore',
+        windowsHide: true, env: consoleEnv(env, receipt.port) });
+      child.on?.('error', () => {});
+      child.unref?.();
+    } catch (error) { refuse(`could not start the current Console: ${error.message}`); continue; }
+    // Done = the scope's receipt names the new runtime from a new live process AND the old process
+    // is gone (the launcher falls back to a free port if the old one never lets go — that is not a
+    // replacement, it is two Consoles).
+    const until = Date.now() + timeoutMs;
+    let current = null;
+    let oldAlive = true;
+    while (Date.now() < until) {
+      const seen = readJson(file);
+      current = seen?.sourceSha256 === identity.sourceSha256 && seen.pid !== receipt.pid && alive(seen.pid) ? seen : null;
+      oldAlive = alive(receipt.pid);
+      if (current && !oldAlive) break;
+      sleepSync(200);
+    }
+    const secs = Math.round(timeoutMs / 1000);
+    if (current && !oldAlive) { results.push({ ...where, replaced: true, newPid: current.pid, newPort: current.port }); continue; }
+    if (current) refuse(`the current Console started (pid ${current.pid}, port ${current.port}) but the old one (pid ${receipt.pid}) did not exit within ${secs}s`);
+    else if (oldAlive) refuse(`the old Console (pid ${receipt.pid}) did not release port ${receipt.port} within ${secs}s`);
+    else refuse(`the old Console stopped but the current one did not report the new runtime within ${secs}s`);
+  }
+  return results;
+}

package/scripts/console-runtime-identity.mjs

@@ -42,6 +42,8 @@ export const CONSOLE_RUNTIME_SURFACE = Object.freeze([
   // Keep their bytes in the same copy/digest authority as the installer itself.
   'kb/refresh-run.mjs',
   'kb/lifecycle-evidence-retention.mjs',
+  // install.mjs --update recovers an interrupted storage transaction before it looks for the updater.
+  'kb/update-storage-transaction.mjs',
   'kb/model-requirements.mjs',
   'kb/zip-extract.mjs',
   // install.mjs imports this STATICALLY (corpus transport identity + approved-runtime stamping,

package/scripts/corpus-canary.mjs

@@ -42,7 +42,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { addPrivateStore, resolveRuntime, resultFromRefreshReceipt, runInstallerDoor } from './customer-seams.mjs';
 import { CANARY_VERDICT_KIND, CORPUS_TAG_PATTERN, REQUIRED_CANARY_CHECKS } from './corpus-promotion.mjs';
 
 export const PUBLIC_API = 'https://api.github.com';
@@ -284,7 +285,7 @@ export function installCustomer({ approvedVersion, work, home, log = () => {} })
   runLogged(process.execPath, [installer, '--yes', '--force', '--version', `v${approvedVersion}`, '--no-nightly-prompt',
     '--no-telemetry', '--no-stack', '--no-enhance', '--no-statusline', '--no-selfcheck'],
   { env, cwd: home, timeoutMs: 1_800_000, log });
-  return { kbDir: env.RUVNET_BRAIN_KB };
+  return { kbDir: env.RUVNET_BRAIN_KB, home };
 }
 
 function runUpdater({ kbDir, env, resultFile }) {
@@ -310,17 +311,35 @@ async function fetchRelease({ apiBase, repo, tag }) {
  * installer); the unit suite hands in a customer tree built offline so the updater, the judge and the
  * verdict run for real without a 555 MB download.
  */
-export async function runCanary({
-  repo, tag, approvedVersion, work, apiBase = PUBLIC_API, install = installCustomer, home = path.join(work, 'home'),
-  env = process.env, now = () => Date.now(), retryDelayMs = 30_000, maxAttempts = 3, log = () => {},
-}) {
-  if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('--repo must be owner/name');
-  if (!CORPUS_TAG_PATTERN.test(String(tag || ''))) throw new Error('--tag must be corpus-sha256-<64 hex>');
-  if (!SEMVER.test(String(approvedVersion || ''))) throw new Error('--approved-version must be X.Y.Z');
+/**
+ * THE CUSTOMER STATES THE CANARY ASKS ABOUT. `clean` is the original (and default) case. The others are
+ * the two states 2026-09-30 showed are not covered by it (scripts/customer-state-matrix.mjs measured
+ * both on real releases): a machine carrying a private overlay, and a machine installed at an OLDER
+ * runtime that reaches the candidate through `npx ruvnet-brain@latest --update`. Each extra case is a
+ * fresh install in its own directory, run AFTER the clean case and deleted before the next, so peak disk
+ * stays one install + one apply. Its checks are the same judge's, prefixed `<case>:`; any failure is a FAIL.
+ */
+export const CANARY_CASES = Object.freeze({
+  clean: Object.freeze({ runtime: 'approved', door: 'updater', overlay: false }),
+  'private-overlay': Object.freeze({ runtime: 'approved', door: 'updater', overlay: true }),
+  'older-runtime': Object.freeze({ runtime: 'N-1', door: 'installer', overlay: false }),
+});
+
+async function fetchReleaseList({ apiBase, repo }) {
+  const response = await fetch(`${apiBase}/repos/${repo}/releases?per_page=100`, { headers: { accept: 'application/vnd.github+json' } });
+  if (!response.ok) throw new Error(`release list returned HTTP ${response.status}`);
+  return response.json();
+}
+
+async function runCase({ name, spec, repo, tag, approvedVersion, release, work, home, apiBase, install, now,
+  retryDelayMs, maxAttempts, log, writerRoot, approvedInstaller }) {
   fs.mkdirSync(home, { recursive: true });
-  const started = now();
-  const { kbDir } = await install({ approvedVersion, work, home, log });
-  const release = await fetchRelease({ apiBase, repo, tag });
+  let runtime = approvedVersion;
+  if (spec.runtime !== 'approved') runtime = resolveRuntime(spec.runtime, { candidateTag: `v${approvedVersion}`, releases: await fetchReleaseList({ apiBase, repo }) });
+  const installed = await install({ approvedVersion: runtime, work, home, log });
+  const { kbDir } = installed;
+  home = installed.home || home;
+  const overlay = spec.overlay ? await addPrivateStore({ kbDir, scratch: work, writerRoot }) : null;
   const beforeModules = installedModules(kbDir);
   const beforeCoverage = coverageRows(path.join(kbDir, 'CORPUS-COVERAGE.json'));
   const { before } = pointUpdaterAtCandidate({ kbDir, apiBase, repo, tag });
@@ -331,15 +350,107 @@ export async function runCanary({
   let updater = { exitCode: null, output: '', attempts: 0 };
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     fs.rmSync(resultFile, { force: true });
-    const run = await runUpdater({ kbDir, env: childEnv, resultFile });
+    const run = spec.door === 'installer'
+      ? await runInstallerDoor({ installer: await approvedInstaller(), env: childEnv, cwd: home })
+      : await runUpdater({ kbDir, env: childEnv, resultFile });
     updater = { ...run, attempts: attempt };
-    log(`--- forge-update.mjs --apply (attempt ${attempt}) exit ${run.exitCode}\n${run.output}`);
+    log(`--- [${name}] ${spec.door === 'installer' ? 'install.mjs --update' : 'forge-update.mjs --apply'} (attempt ${attempt}) exit ${run.exitCode}\n${run.output}`);
     if (run.exitCode !== NETWORK_EXIT || attempt === maxAttempts) break;
     await new Promise((resolve) => setTimeout(resolve, retryDelayMs * attempt));
   }
-  updater.result = fs.existsSync(resultFile) ? readJson(resultFile) : null;
+  updater.result = spec.door === 'installer' ? resultFromRefreshReceipt(childEnv.RUVNET_BRAIN_HOME)
+    : (fs.existsSync(resultFile) ? readJson(resultFile) : null);
   const judged = await judgeCanary({ tag, approvedVersion, release, updater, before, beforeModules, beforeCoverage,
     kbDir: fs.realpathSync(kbDir), home: fs.realpathSync(home), now: now() });
+  if (overlay) {
+    const after = Object.fromEntries(Object.keys(overlay.digests).map((f) => [f,
+      fs.existsSync(path.join(kbDir, f)) ? sha256File(path.join(kbDir, f)) : null]));
+    const changed = Object.keys(after).filter((f) => after[f] !== overlay.digests[f]);
+    judged.checks.push({ name: 'private-store-preserved', ok: changed.length === 0,
+      detail: changed.length ? `private files changed or lost: ${changed.join(', ')}` : `${Object.keys(after).length} private file(s) byte-identical` });
+  }
+  return { updater, checks: judged.checks, runtime };
+}
+
+const physical = (dir) => { try { return fs.realpathSync(dir); } catch { return path.resolve(dir); } };
+
+/**
+ * `--installed-kb`: the clean case runs on the supplied KB (as before); every extra case gets its OWN copy
+ * of that KB as it was BEFORE the clean case touched it, under the case's work dir, so the supplied brain
+ * never gains the overlay case's private store or a rewritten PRIVATE-STORES.json.
+ *
+ * DISK: copies are reflink clones (COPYFILE_FICLONE) where the filesystem supports it (APFS, btrfs, XFS
+ * with reflink) and cost almost nothing; elsewhere (ext4, most CI runners) they are full copies. Then the
+ * peak is the supplied KB + one snapshot + one case copy (each case's copy is deleted before the next),
+ * i.e. about 3x the KB (~4 GB for a 1.3 GB brain). Hardlinks are not used: an update that rewrote a
+ * file in place would write through into the caller's brain.
+ */
+export function suppliedKbInstaller({ installedKb, work, cases }) {
+  const supplied = path.resolve(installedKb);
+  const snapshot = path.join(work, 'supplied-kb-snapshot');
+  const copy = (from, to) => fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true, mode: fs.constants.COPYFILE_FICLONE });
+  if (cases.length > 1) { fs.rmSync(snapshot, { recursive: true, force: true }); copy(supplied, snapshot); }
+  return ({ work: caseWork, home }) => {
+    if (path.resolve(caseWork) === path.resolve(work)) return { kbDir: supplied };
+    const kbDir = path.join(home, '.cache', 'ruvnet-brain', 'kb');
+    fs.mkdirSync(path.dirname(kbDir), { recursive: true });
+    copy(snapshot, kbDir);
+    return { kbDir, home };
+  };
+}
+
+export async function runCanary({
+  repo, tag, approvedVersion, work, apiBase = PUBLIC_API, install = installCustomer, home = path.join(work, 'home'),
+  env = process.env, now = () => Date.now(), retryDelayMs = 30_000, maxAttempts = 3, log = () => {},
+  cases = ['clean'], writerRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
+  approvedInstaller = null,
+}) {
+  if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('--repo must be owner/name');
+  if (!CORPUS_TAG_PATTERN.test(String(tag || ''))) throw new Error('--tag must be corpus-sha256-<64 hex>');
+  if (!SEMVER.test(String(approvedVersion || ''))) throw new Error('--approved-version must be X.Y.Z');
+  if (cases[0] !== 'clean' || cases.some((name) => !CANARY_CASES[name])) {
+    throw new Error(`--cases must start with clean and name only: ${Object.keys(CANARY_CASES).join(', ')}`);
+  }
+  const started = now();
+  const release = await fetchRelease({ apiBase, repo, tag });
+  // The approved package's installer — what `npx ruvnet-brain@latest` runs — fetched once, on demand.
+  let installerPath = null;
+  const resolveInstaller = approvedInstaller || (async () => {
+    if (installerPath) return installerPath;
+    const prefix = path.join(work, 'approved-npx');
+    fs.mkdirSync(prefix, { recursive: true });
+    const npm = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    runLogged(npm, ['install', '--prefix', prefix, '--no-audit', '--no-fund', '--no-save', `ruvnet-brain@${approvedVersion}`],
+      { env: customerEnv({ home, work }), cwd: prefix, timeoutMs: 600_000, log });
+    installerPath = path.join(prefix, 'node_modules', 'ruvnet-brain', 'bin', 'install.mjs');
+    return installerPath;
+  });
+  const common = { repo, tag, approvedVersion, release, apiBase, install, now, retryDelayMs, maxAttempts, log, writerRoot,
+    approvedInstaller: resolveInstaller };
+  let cleanKb = null;
+  const clean = await runCase({ ...common, name: 'clean', spec: CANARY_CASES.clean, work, home,
+    install: async (args) => { const installed = await install(args); cleanKb = physical(installed.kbDir); return installed; } });
+  const { updater } = clean;
+  const judged = { checks: [...clean.checks] };
+  for (const name of cases.slice(1)) {
+    const caseWork = path.join(work, `case-${name}`);
+    let outcome;
+    try {
+      // An extra case adds a private store and rewrites PRIVATE-STORES.json: it must never do that to the
+      // clean case's KB (with --installed-kb, the caller's own brain). Each case gets its own tree.
+      const caseInstall = async (args) => {
+        const installed = await install(args);
+        if (physical(installed.kbDir) === cleanKb) throw new Error(`case ${name} was handed the clean case's KB (${installed.kbDir}); refusing to mutate it`);
+        return installed;
+      };
+      outcome = await runCase({ ...common, install: caseInstall, name, spec: CANARY_CASES[name], work: caseWork, home: path.join(caseWork, 'home') });
+    } catch (error) {
+      outcome = { checks: [{ name: 'case-ran', ok: false, detail: error.message }] };
+    }
+    for (const entry of outcome.checks) judged.checks.push({ ...entry, name: `${name}:${entry.name}` });
+    fs.rmSync(caseWork, { recursive: true, force: true });
+  }
+  judged.verdict = judged.checks.every((entry) => entry.ok) ? 'PASS' : 'FAIL';
   return {
     schemaVersion: 1,
     kind: CANARY_VERDICT_KIND,
@@ -365,18 +476,19 @@ async function main(argv = process.argv.slice(2)) {
   const work = opt('--work') && path.resolve(opt('--work'));
   const verdictOut = opt('--verdict-out') && path.resolve(opt('--verdict-out'));
   if (!work || !verdictOut) {
-    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>]\n');
+    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--cases clean,private-overlay,older-runtime]\n');
     return 2;
   }
   fs.mkdirSync(work, { recursive: true });
   const logFile = path.join(work, 'canary.log');
   const log = (text) => { fs.appendFileSync(logFile, `${text}\n`); };
   const installedKb = opt('--installed-kb');
-  const install = installedKb ? () => ({ kbDir: path.resolve(installedKb) }) : installCustomer;
+  const cases = String(opt('--cases') || 'clean').split(',').map((name) => name.trim()).filter(Boolean);
+  const install = installedKb ? suppliedKbInstaller({ installedKb, work, cases }) : installCustomer;
   let record;
   try {
     record = await runCanary({ repo: opt('--repo'), tag: opt('--tag'), approvedVersion: opt('--approved-version'), work,
-      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log });
+      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log, cases });
   } catch (error) {
     // Could not even reach a judgement = the consumer did not accept. Still a written verdict.
     record = { schemaVersion: 1, kind: CANARY_VERDICT_KIND, verdict: 'FAIL', repo: opt('--repo') || null, tag: opt('--tag') || null,

package/scripts/customer-seams.mjs

@@ -0,0 +1,84 @@
+// scripts/customer-seams.mjs — the customer-side seams shared by scripts/corpus-canary.mjs (the nightly
+// consumer gate) and scripts/customer-state-matrix.mjs (the same seams across many machine states). One copy.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const sha256File = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+const SEMVER_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+/** `N-k`: the k-th published (non-draft) semver code release behind `candidateTag`, from a live release list. */
+export function resolveRuntime(offset, { candidateTag, releases }) {
+  const match = /^N-(\d+)$/.exec(offset);
+  if (!match) throw new Error(`runtime offset must be N-<k>: ${offset}`);
+  const key = (tag) => SEMVER_TAG.exec(tag).slice(1).map(Number);
+  const cmp = (a, b) => { const [x, y] = [key(a), key(b)]; return y[0] - x[0] || y[1] - x[1] || y[2] - x[2]; };
+  const tags = releases.filter((r) => !r.draft && SEMVER_TAG.test(r.tag_name || '')).map((r) => r.tag_name).sort(cmp);
+  const at = tags.indexOf(candidateTag);
+  if (at < 0) throw new Error(`candidate ${candidateTag} is not a published code release`);
+  const tag = tags[at + Number(match[1])];
+  if (!tag) throw new Error(`no published release ${offset} behind ${candidateTag}`);
+  return tag.slice(1);
+}
+
+/**
+ * A customer's PRIVATE store: the smallest real public store family, renamed, stamped by the product's
+ * own writer (scripts/private-overlay.mjs) with an alias and a capability card — the same shape the
+ * owner's 108 private stores have. Exercises capture -> candidate restore -> coverage convergence.
+ */
+export async function addPrivateStore({ kbDir, scratch, writerRoot, name = 'acme-private-notes' }) {
+  const ledger = readJson(path.join(kbDir, 'RVF-GENERATIONS.json')).stores;
+  const donor = Object.entries(ledger).filter(([, g]) => /\.big\.rvf$/.test(g.file || ''))
+    .sort(([, a], [, b]) => a.bytes - b.bytes)[0][0];
+  const from = path.join(scratch, 'private-sidecars');
+  fs.mkdirSync(from, { recursive: true });
+  for (const file of fs.readdirSync(kbDir).filter((f) => f.startsWith(`${donor}.`) || f === `${donor}-primer.md`)) {
+    fs.copyFileSync(path.join(kbDir, file), path.join(from, file.replace(donor, name)));
+  }
+  const { applyPrivateOverlay } = await import(pathToFileURL(path.join(writerRoot, 'scripts', 'private-overlay.mjs')).href);
+  const card = path.join(scratch, `${name}.card.md`);
+  fs.writeFileSync(card, `Private notes (a renamed copy of ${donor}). Reach for it only for this customer's own material.\n`);
+  // The fence comes first, exactly as the writer demands of a customer (PRIVATE-STORES.json).
+  const fenceFile = path.join(kbDir, 'PRIVATE-STORES.json');
+  const fence = fs.existsSync(fenceFile) ? readJson(fenceFile) : { privateStores: [] };
+  fs.writeFileSync(fenceFile, `${JSON.stringify({ ...fence, privateStores: [...new Set([...(fence.privateStores || []), name])] }, null, 2)}\n`);
+  applyPrivateOverlay({ root: kbDir, from, stores: [name], aliases: { [name]: [`${name}-alias`] }, cards: { [name]: card } });
+  const digests = Object.fromEntries(fs.readdirSync(kbDir).filter((f) => f.startsWith(`${name}.`) || f.startsWith(`${name}-`))
+    .sort().map((f) => [f, sha256File(path.join(kbDir, f))]));
+  return { name, donor, digests };
+}
+
+/**
+ * The `npx ruvnet-brain@latest --update` door: the APPROVED package's own installer, which self-upgrades
+ * the installed updater, re-stamps the runtime, takes the refresh lock and runs the updater. Fallback is
+ * disabled for the same reason the clean case never uses this door: a refused candidate must not turn
+ * into a green fresh install. The updater's receipt is reconstructed from the refresh-run receipt the
+ * installer settles (the installer deletes its private result file).
+ */
+export function runInstallerDoor({ installer, env, cwd }) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [installer, '--update', '--no-nightly-prompt'],
+      { cwd, env: { ...env, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.stderr.on('data', (chunk) => { output += chunk; });
+    child.on('error', (error) => resolve({ exitCode: null, output: `${output}\n${error.message}` }));
+    child.on('close', (exitCode) => resolve({ exitCode, output }));
+  });
+}
+
+export function resultFromRefreshReceipt(brainHome) {
+  const dir = path.join(brainHome, 'refresh-runs');
+  if (!fs.existsSync(dir)) return null;
+  const newest = fs.readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => path.join(dir, f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0];
+  if (!newest) return null;
+  const receipt = readJson(newest);
+  const phase = (name) => receipt.phases?.find((p) => p.phase === name)?.evidence || {};
+  return { terminalVerdict: receipt.status === 'SUCCEEDED' ? phase('update').terminalVerdict || null : receipt.terminalVerdict,
+    bundleSha256: phase('bundle-assembly').bundleSha256 || null, coverageSha256: phase('coverage-generation').coverageSha256 || null,
+    refreshStatus: receipt.status };
+}