ruvnet-brain 4.3.40 → 4.4.0

package/plugin/scripts/session-snapshot-hook.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ProgressionOutbox } from './project-progression-outbox.mjs';
 import {
   captureProjectTransition,
   hasProjectProgression,
@@ -19,6 +21,23 @@ import { captureTurnOutcome } from './turn-outcome-capture.mjs';
  */
 export const CAPTURE_BUDGET_MS = 8_000;
 
+/**
+ * Replaying an interrupted session's outbox costs one `ruflo` write per pending snapshot, each ~3s
+ * cold (project-progression-store.mjs). Under this budget there is room for the NEW snapshot or the
+ * old ones, not both — and the new one is the one nothing else will ever write.
+ */
+export const REPLAY_MIN_BUDGET_MS = 4_000;
+
+/**
+ * The budget this invocation really has. The Codex wrapper hands its own kill deadline down as
+ * RUVNET_CODEX_BUDGET_MS (2200ms at SessionEnd, which Codex caps at 3s); planning for 8s there meant
+ * being SIGKILLed mid-write with nothing reported. 300ms is left for the adapter → shim → body spawns.
+ */
+export function effectiveBudgetMs(env = process.env) {
+  const handed = Number(env.RUVNET_CODEX_BUDGET_MS);
+  return Number.isFinite(handed) && handed > 0 ? Math.max(0, Math.min(CAPTURE_BUDGET_MS, handed - 300)) : CAPTURE_BUDGET_MS;
+}
+
 function regularOrAbsent(file) {
   try {
     const stat = fs.lstatSync(file);
@@ -96,11 +115,16 @@ export function runSessionSnapshotHook(projectDir, event, {
   host = process.env.RUVNET_HOOK_HOST || 'claude',
   captureProgression = captureProjectTransition,
   produce = buildProjectProgression,
-  budgetMs = CAPTURE_BUDGET_MS,
+  budgetMs = effectiveBudgetMs(),
   now = Date.now,
   captureTurn = captureTurnOutcome,
+  writeMetadata = true,
+  makeStoreFactory = boundedStoreFactory,
+  spawnReplay = replayOutboxDetached,
+  ordered = null,
 } = {}) {
-  const metadataWritten = writeSessionSnapshot(projectDir, event);
+  // The detached worker re-runs a QUEUED boundary; its session receipt was already written then.
+  const metadataWritten = writeMetadata ? writeSessionSnapshot(projectDir, event) : false;
   let payload;
   try { payload = rawInput ? JSON.parse(rawInput) : {}; } catch { payload = {}; }
   // TURN OUTCOMES FIRST, and independent of `.swarm`: every turn in every repository is recorded
@@ -134,51 +158,213 @@ export function runSessionSnapshotHook(projectDir, event, {
     return { ...idle, skipped: 'project has not adopted the canonical store' };
   }
 
-  const deadlineAt = now() + budgetMs;
-  const storeFactory = boundedStoreFactory(deadlineAt);
+  const root = resolution.projectRoot;
+  const pendingCount = () => {
+    try { return new ProgressionOutbox({ projectRoot: root }).pendingSnapshots().length; } catch { return 0; }
+  };
 
-  // Commit anything a previously interrupted session left durable-but-uncommitted. SessionStart is
-  // forbidden from doing this (ADR-073 §5) because replay is a write; a capture boundary already
-  // owns a write budget, so this is where that debt is settled.
-  let replayed = 0;
-  try {
-    replayed = storeFactory({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath }).replay().length;
-  } catch { /* the new capture below is still worth attempting */ }
+  // CAUSAL ORDER. The producer links a new snapshot to the COMMITTED heads
+  // (project-progression-producer.mjs), so a snapshot produced while older work is uncommitted would
+  // not descend from it and the project would end with two unrelated heads
+  // (tests/acceptance/cross-host-project-resume.test.mjs). "Older work" is BOTH the outbox (captures
+  // interrupted after their fsync) AND the capture queue (whole boundaries waiting for a worker).
+  //
+  // THE REPLAY LOCK IS THE RIGHT TO COMMIT IN ORDER (4.4.0 re-review S-A). Every boundary takes it
+  // before doing anything that commits. If it cannot — a live worker holds it — or older work is
+  // queued, or (on a short budget) outbox debt cannot be replayed here, this boundary QUEUES itself
+  // behind that work and the lock passes to a DETACHED, bounded worker that drains everything in
+  // order. On Codex no boundary has the replay budget (Stop 3700ms effective, SessionEnd 1900ms, no
+  // PreCompact). Any boundary, of any budget, therefore also drains a queue a dead worker stranded.
+  // `ordered` is the worker's own re-entry: it already holds the lock and is draining in order.
+  let token = ordered;
+  const handOff = (why) => {
+    const queued = queueCapture({ projectDir: root, event, host, payload });
+    const handed = queued ? spawnReplay({ projectDir: root, token }) : false;
+    if (!handed && token && token !== ordered) releaseReplayLock(root, token);
+    return { ...idle, replayed: 0, progressionCaptured: false, deferredToReplayer: Boolean(queued),
+      replaySkipped: `${why}; this capture ${queued ? 'queued behind it' : 'NOT queued (queue unwritable)'}`
+        + `${queued ? (handed ? ', handed to a detached worker' : ' (a live worker holds the lock and drains the queue)') : ''}` };
+  };
+  if (!ordered) {
+    token = takeReplayLock(root);
+    if (!token) return handOff('a worker is committing older work');
+    const queuedAhead = queuedCaptures(root).length;
+    if (queuedAhead) return handOff(`${queuedAhead} older capture(s) queued`);
+    if (budgetMs < REPLAY_MIN_BUDGET_MS) {
+      const pending = pendingCount();
+      if (pending) return handOff(`outbox replay deferred: budget ${budgetMs}ms < ${REPLAY_MIN_BUDGET_MS}ms; ${pending} pending`);
+    }
+  }
 
-  let produced;
+  let handedLock = false;
   try {
-    produced = produce({ resolution, payload, host, trigger: event });
-  } catch (error) {
-    return { ...idle, replayed, skipped: `producer failed: ${error.message}` };
+    const deadlineAt = now() + budgetMs;
+    const storeFactory = makeStoreFactory(deadlineAt);
+    let replayed = 0;
+    if (budgetMs >= REPLAY_MIN_BUDGET_MS) {
+      try {
+        replayed = storeFactory({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath }).replay().length;
+      } catch { /* the debt stays durable in the outbox; this capture is still worth attempting */ }
+    }
+
+    let produced;
+    try {
+      produced = produce({ resolution, payload, host, trigger: event });
+    } catch (error) {
+      return { ...idle, replayed, skipped: `producer failed: ${error.message}` };
+    }
+    if (produced.skipped) return { ...idle, replayed, skipped: produced.skipped.reason };
+
+    let result;
+    try {
+      result = captureProgression({
+        host,
+        payload: { ...payload, hook_event_name: event, projectProgression: produced.projectProgression },
+        projectDir,
+        storeFactory,
+      });
+    } catch (error) {
+      // NOT LOST — DEFERRED. capture() fsyncs the snapshot to the durable outbox BEFORE it writes to
+      // the store, so a budget overrun leaves the evidence on disk. On a short budget nothing later in
+      // this process can settle it, so the lock goes straight to a detached worker.
+      handedLock = !ordered && budgetMs < REPLAY_MIN_BUDGET_MS && pendingCount() > 0 && spawnReplay({ projectDir: root, token });
+      return { ...idle, replayed, skipped: `capture deferred: ${error.message}`,
+        ...(handedLock ? { replaySkipped: 'deferred capture handed to a detached worker' } : {}) };
+    }
+    return {
+      metadataWritten,
+      progressionCaptured: true,
+      turn,
+      replayed,
+      receipt: result.receipt,
+      provenance: produced.provenance,
+    };
+  } finally {
+    if (!ordered && !handedLock) releaseReplayLock(root, token);
   }
-  if (produced.skipped) return { ...idle, replayed, skipped: produced.skipped.reason };
+}
+
+/**
+ * How long the detached worker may spend per step. The lock is refreshed between steps and goes stale
+ * after REPLAY_LOCK_STALE_MS, which is more than twice a step, so a live worker never looks dead.
+ */
+export const DETACHED_REPLAY_BUDGET_MS = 45_000;
+export const REPLAY_LOCK_STALE_MS = 120_000;
+const REPLAY_LOCK = '.progression-replay.lock';
+const QUEUE_PREFIX = '.progression-capture-queue-';
+const lockPath = (projectDir) => path.join(projectDir, '.swarm', REPLAY_LOCK);
+const readLock = (projectDir) => { try { return fs.readFileSync(lockPath(projectDir), 'utf8').trim(); } catch { return null; } };
+let queueSeq = 0;
 
-  let result;
+/** Queue one boundary's capture for the worker (0600, inside the project's own .swarm), in arrival order. */
+export function queueCapture({ projectDir, event, host, payload, now = Date.now() }) {
   try {
-    result = captureProgression({
-      host,
-      payload: { ...payload, hook_event_name: event, projectProgression: produced.projectProgression },
-      projectDir,
-      storeFactory,
+    queueSeq += 1;
+    const name = `${QUEUE_PREFIX}${String(now).padStart(15, '0')}-${String(process.hrtime.bigint() % 1_000_000_000n).padStart(9, '0')}-${process.pid}-${queueSeq}.json`;
+    const file = path.join(projectDir, '.swarm', name);
+    fs.writeFileSync(file, JSON.stringify({ event, host, payload }), { flag: 'wx', mode: 0o600 });
+    return file;
+  } catch { return null; }
+}
+
+export function queuedCaptures(projectDir) {
+  try {
+    return fs.readdirSync(path.join(projectDir, '.swarm')).filter((n) => n.startsWith(QUEUE_PREFIX) && n.endsWith('.json'))
+      .sort().map((n) => path.join(projectDir, '.swarm', n));
+  } catch { return []; }
+}
+
+/**
+ * Take the lock. Returns this holder's TOKEN, or null when a live holder has it. A lock not refreshed
+ * for REPLAY_LOCK_STALE_MS belongs to a dead worker and is taken over: renamed aside first, so two
+ * would-be successors cannot both win the exclusive create.
+ */
+export function takeReplayLock(projectDir, now = Date.now()) {
+  const lock = lockPath(projectDir);
+  const token = `${process.pid}-${now}-${Math.random().toString(36).slice(2, 10)}`;
+  const create = () => { fs.writeFileSync(lock, `${token}\n`, { flag: 'wx', mode: 0o600 }); return token; };
+  try { return create(); } catch { /* held, or stale */ }
+  try {
+    if (now - fs.statSync(lock).mtimeMs <= REPLAY_LOCK_STALE_MS) return null;
+    const aside = `${lock}.stale-${process.pid}-${now}`;
+    fs.renameSync(lock, aside);
+    fs.rmSync(aside, { force: true });
+    return create();
+  } catch { return null; }
+}
+
+/** Heartbeat: refresh the lock's mtime if (and only if) this holder still owns it. */
+export function refreshReplayLock(projectDir, token) {
+  if (!token || readLock(projectDir) !== token) return false;
+  try { const t = new Date(); fs.utimesSync(lockPath(projectDir), t, t); return true; } catch { return false; }
+}
+
+/** Release ONLY a lock this holder owns; a successor's lock is never deleted. */
+export function releaseReplayLock(projectDir, token) {
+  if (!token || readLock(projectDir) !== token) return false;
+  try { fs.rmSync(lockPath(projectDir), { force: true }); return true; } catch { return false; }
+}
+
+/** Hand the lock (or take it, if free) to a detached worker. Returns whether one was started. Never throws. */
+export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn } = {}) {
+  const held = token || takeReplayLock(projectDir);
+  if (!held) return false;
+  try {
+    const child = spawnFn(process.execPath, [fileURLToPath(import.meta.url), '--replay-outbox'], {
+      cwd: projectDir, detached: true, stdio: 'ignore', windowsHide: true,
+      env: { ...process.env, RUVNET_REPLAY_LOCK_TOKEN: held },
     });
-  } catch (error) {
-    // NOT LOST — DEFERRED. capture() fsyncs the snapshot to the durable outbox BEFORE it writes to
-    // the store, so a budget overrun here leaves the evidence on disk and the next capture boundary
-    // (or /checkpoint) commits it. Reporting that plainly is the whole difference between a bounded
-    // hook and a lossy one, so the reason is returned rather than thrown at a lifecycle boundary.
-    return { ...idle, replayed, skipped: `capture deferred: ${error.message}` };
+    child.unref?.();
+    return true;
+  } catch {
+    releaseReplayLock(projectDir, held);
+    return false;
   }
-  return {
-    metadataWritten,
-    progressionCaptured: true,
-    turn,
-    replayed,
-    receipt: result.receipt,
-    provenance: produced.provenance,
-  };
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
+/**
+ * The detached worker's body, holding the lock `token`: replay the outbox, then run every queued capture
+ * IN ORDER — each re-entering the boundary as `ordered`, so it replays before it produces — refreshing
+ * the lock between steps and STOPPING the moment the lock is no longer its own (a successor took it
+ * over: running on would duplicate its work). Releases only its own lock, then re-checks for captures
+ * queued while it held it.
+ */
+export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_LOCK_TOKEN || null, budgetMs = DETACHED_REPLAY_BUDGET_MS,
+  makeStoreFactory = boundedStoreFactory, now = Date.now, runCapture = runSessionSnapshotHook } = {}) {
+  let held = token || takeReplayLock(projectDir);
+  let replayed = 0;
+  for (let round = 0; held && round < 8; round += 1) {
+    try {
+      if (!refreshReplayLock(projectDir, held)) return replayed;
+      const resolution = resolveProjectStore({ projectDir });
+      const store = makeStoreFactory(now() + budgetMs)({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath });
+      for (const snapshot of store.outbox.pendingSnapshots()) {
+        if (!refreshReplayLock(projectDir, held)) return replayed;
+        store.outbox.markCommitted(store.appendExact(snapshot));
+        replayed += 1;
+      }
+      for (const file of queuedCaptures(projectDir)) {
+        if (!refreshReplayLock(projectDir, held)) return replayed;
+        let job = null;
+        try { job = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* torn: dropped below */ }
+        try {
+          if (job) runCapture(projectDir, job.event, { rawInput: JSON.stringify(job.payload), host: job.host,
+            budgetMs, makeStoreFactory, now, ordered: held, writeMetadata: false,
+            captureTurn: () => ({ recorded: false, skipped: 'detached replay' }) });
+        } catch { /* a failed capture leaves its own snapshot durable in the outbox */ }
+        try { fs.rmSync(file, { force: true }); } catch { /* best effort */ }
+      }
+    } catch { /* the debt stays durable; the next boundary hands it on again */ } finally {
+      releaseReplayLock(projectDir, held);
+    }
+    held = queuedCaptures(projectDir).length ? takeReplayLock(projectDir) : null;
+  }
+  return replayed;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs') && process.argv[2] === '--replay-outbox') {
+  try { runOutboxReplay({ projectDir: process.cwd() }); } catch { /* the debt stays durable in the outbox */ }
+} else if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
   // projectDirectory() is the SAME derivation the Console's detector uses. Deriving it here
   // independently is what let this hook write a receipt the Console then reported as missing (#85).
   const rawInput = fs.readFileSync(0, 'utf8');

package/plugin/scripts/session-start-health.mjs

@@ -93,13 +93,29 @@ export const knowledgeFacts = ({ env = process.env, home, now = Date.now() } = {
     lockMs: Date.parse(json(auto.lockFile)?.at || '') || mtimeMs(auto.lockFile) };
 };
 
+/**
+ * agentic-kit ownership is a CLAIM in kit.json, not a delivery: on the owner's Mac (2026-09-30)
+ * kit.json said ruvnetBrain:true while agentic-kit scheduled nothing, so the self-heal stood down
+ * forever and the knowledge base aged by hand only. Ownership is honoured only while an update is
+ * PROVEN inside this window (a successful refresh receipt or a CURRENT --check verdict); 36h leaves
+ * the self-heal 12h to land one before the 48h invariant breaks.
+ */
+export const AGENTIC_KIT_PROOF_HOURS = 36;
+/** 'none' | 'delivering' (kit.json claims it AND an update is proven) | 'not-delivering'. */
+export const agenticKitUpdates = ({ home, facts }) => {
+  if (!updateOwnedByAgenticKit(home)) return 'none';
+  return facts.provenWithin(AGENTIC_KIT_PROOF_HOURS) ? 'delivering' : 'not-delivering';
+};
+
 /** Why the SessionStart knowledge auto-update may NEVER run on this machine ('' = it may). */
 export const autoUpdateOptOut = ({ env = process.env, home, facts }) => {
   const flag = String(env.RUVNET_AUTO_UPDATE || '').toLowerCase();
   if (flag === 'off') return 'RUVNET_AUTO_UPDATE=off';
   if (env.RUVNET_BRAIN_TEST === '1' && flag !== 'on') return 'test mode';
   if (read(path.join(facts.brainHome, '.auto-update-pref')).trim() === 'no') return 'you answered no to background auto-update';
-  if (updateOwnedByAgenticKit(home)) return 'agentic-kit owns updates: ak sync';
+  if (agenticKitUpdates({ home, facts }) === 'delivering') {
+    return `agentic-kit owns updates and one is proven within ${AGENTIC_KIT_PROOF_HOURS}h: ak sync`;
+  }
   if (!exists(path.join(facts.kbDir, 'forge-update.mjs'))) return 'this install predates the self-updater';
   return '';
 };
@@ -122,8 +138,10 @@ export const knowledgeCurrency = ({ env = process.env, home, now = Date.now(), w
   const ageKnown = Number.isFinite(builtMs);
   if (!failing && proven) return '';
   if (!failing && ageKnown && hours(builtMs) <= windowHours) return '';
-  const agentKit = updateOwnedByAgenticKit(home);
-  const scheduled = agentKit || readNightlyRegistration({ brainHome }).ok;
+  const kit = agenticKitUpdates({ home, facts });
+  const agentKit = kit === 'delivering';
+  // An agentic-kit machine must never be told to also --enable-nightly (one owner per machine).
+  const scheduled = kit !== 'none' || readNightlyRegistration({ brainHome }).ok;
   const parts = [ageKnown ? `knowledge base built ${day(builtMs)} (${age(builtMs)})`
     : 'knowledge base age UNKNOWN (SOURCE.json missing or unreadable)'];
   if (autoFailed) {
@@ -138,6 +156,9 @@ export const knowledgeCurrency = ({ env = process.env, home, now = Date.now(), w
   parts.push(history.receipts
     ? `${history.failuresSinceSuccess} failed run(s) since the last success (${history.lastSuccess ? day(history.lastSuccess.at) : 'none recorded'})`
     : 'no refresh has ever run on this machine');
+  if (kit === 'not-delivering') {
+    parts.push(`agentic-kit claims updates (kit.json ruvnetBrain:true) but no update is proven in ${AGENTIC_KIT_PROOF_HOURS}h, so the Brain's own self-heal runs instead`);
+  }
   if (!scheduled) parts.push('no nightly refresh is scheduled');
   if (history.unreadable) parts.push(`${history.unreadable} unreadable receipt(s)`);
   const fix = agentKit ? 'ak sync' : scheduled ? 'npx ruvnet-brain@latest --update'

package/plugin/scripts/session-start-update-plane.mjs

@@ -145,7 +145,7 @@ export const heartbeat = ({ env, hookDir, stateDir, home, running, seedDispatche
   if (pref === 'yes' && exists(path.join(kbDir, 'forge-update.mjs'))) {
     const kbLog = path.join(stateDir, '.last-kb-check.log');
     if (/\bBEHIND\b/.test(read(kbLog))) {
-      emit('[RuvNet Brain — a newer knowledge bundle is available. It is signed (Ed25519) and the updater verifies that signature before extracting anything. We do NOT auto-apply it: applying replaces executable tool files, which is your call. To update: cd ~/.cache/ruvnet-brain/kb && node forge-update.mjs --apply]');
+      emit('[RuvNet Brain — a newer knowledge bundle is available. It is signed (Ed25519) and the updater verifies that signature before extracting anything. We do NOT auto-apply it: applying replaces executable tool files, which is your call. To update: npx ruvnet-brain@latest --update]');
     }
     // S2 (ONE CURRENCY VERDICT): --result-file records the SAME structured verdict --check/--apply
     // and bin/install.mjs already read (forge-update.mjs's currencyVerdict()), at the well-known path

package/plugin/scripts/update-apply.mjs

@@ -53,10 +53,19 @@ const RECEIPTS = path.join(BRAIN_HOME, 'update-receipts.jsonl');
 const LEASES = path.join(BRAIN_HOME, 'leases');
 const DEV = path.join(BRAIN_HOME, 'dev.json');
 const SEEDED = path.join(BRAIN_HOME, '.spine-seeded');
+// Claude Code honours CLAUDE_CONFIG_DIR for its whole config tree, plugins included; Codex honours CODEX_HOME.
+const CLAUDE_CONFIG = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const CODEX_CONFIG = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
 const PLUGIN_CACHES = [
-  path.join(os.homedir(), '.claude', 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain'),
-  path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain'),
+  path.join(CLAUDE_CONFIG, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain'),
+  path.join(CODEX_CONFIG, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain'),
 ];
+// Evidence that a host has been pointed at the Brain's plugin at all (marketplace registered or plugin
+// cache created) — even when `plugin install` then failed and staged nothing.
+const HOST_PLUGIN_EVIDENCE = [CLAUDE_CONFIG, CODEX_CONFIG].flatMap((root) => [
+  path.join(root, 'plugins', 'marketplaces', 'ruvnet-brain'),
+  path.join(root, 'plugins', 'cache', 'ruvnet-brain'),
+]);
 const LEASE_FRESH_MS = 6 * 3600_000; // a lease older than 6h is stale (its process is long gone)
 
 const argv = process.argv.slice(2);
@@ -425,6 +434,17 @@ function main() {
           console.log(`already on ${activeNow.version}, at or above requested ${expectedVersion} — nothing to apply.`);
           return 0;
         }
+        // NO HOST AT ALL is not a stale spine. With no active spine and no payload of ANY version in
+        // any host cache, nothing was ever seeded, so nothing can be behind (a desktop-app/IDE-extension
+        // customer whose shell has no host CLI). A host cache holding some OTHER version still fails
+        // closed below — issue #64's exact-selection guard is untouched.
+        // Existence, not a parse: a corrupt active.json is a damaged spine and still fails closed below.
+        // A host that registered the Brain's plugin but staged nothing (its `plugin install` failed) is
+        // NOT "no host": that is a failed install and must keep failing.
+        if (!fs.existsSync(ACTIVE) && !newestStagedCC() && !HOST_PLUGIN_EVIDENCE.some((dir) => fs.existsSync(dir))) {
+          console.log(`no host has staged a payload and no spine is active — nothing to converge for ${expectedVersion}.`);
+          return 0;
+        }
         console.error(`✗ no staged host payload exactly matches expected version ${expectedVersion} — spine unchanged`);
         return 1;
       }

package/scripts/console-instances.mjs

@@ -0,0 +1,145 @@
+// 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]);
+
+/**
+ * Console receipts in `receiptDir`, with dead ones pruned. A receipt is dead only when BOTH hold:
+ * its pid is not alive, and its port does not answer /api/runtime with the receipt's identity.
+ * A receipt with no integer pid cannot be proven dead and is kept (counted as before).
+ */
+export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = probeRuntimeSync } = {}) {
+  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 && !alive(receipt.pid)) {
+      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 });
+        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']);
+const CONSOLE_ENV_DENY_PREFIX = /^(?:RUVNET_NIGHTLY_|npm_|VITEST)/;
+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,