ruvnet-brain 4.3.40 → 4.4.1

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,373 @@ 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;
+  // 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' : ' (the current lock holder hands the queue to a worker when it releases)') : ''}` };
+  };
+  if (!ordered) {
+    token = takeReplayLock(root);
+    if (!token) return handOff('a worker is committing older work');
+    const queuedAhead = queuedWork(root);
+    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 handedLock = false;
   try {
-    replayed = storeFactory({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath }).replay().length;
-  } catch { /* the new capture below is still worth attempting */ }
+    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 */ }
+    }
+
+    // Before COMMITTING anything, re-check the lock is still ours: with three racers, a stale-lock
+    // put-back can leave a holder that no longer owns it. One that lost it queues itself instead.
+    if (!ordered && !refreshReplayLock(root, token)) {
+      token = null;
+      handedLock = true;   // nothing of ours to release
+      return handOff('the lock was taken over before this capture committed');
+    }
+
+    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 {
+    // A boundary that fired while this one held the lock queued itself and could not start a worker
+    // (this lock was in the way). Releasing without looking stranded it until the next boundary — two
+    // simultaneous SessionEnds lost the second one's final state (4.4.1). So: queued work → hand THIS
+    // lock to a worker; and re-check after releasing, for a boundary that queued in between.
+    if (!ordered && !handedLock) {
+      if (!(queuedWork(root) && spawnReplay({ projectDir: root, token }))) {
+        releaseReplayLock(root, token);
+        if (queuedWork(root)) spawnReplay({ projectDir: root });
+      }
+    }
+  }
+}
+
+/**
+ * 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);
+// The lock's FIRST line is the owner token; a second `pid <n>` line names the process holding it.
+const readLock = (projectDir) => { try { return fs.readFileSync(lockPath(projectDir), 'utf8').split('\n')[0].trim(); } catch { return null; } };
+const CLAIM_PREFIX = '.progression-capture-claimed-';
+/** After this long a stale lock is taken over even if its holder pid looks alive (pid reuse, a wedged process). */
+export const REPLAY_LOCK_ABANDON_MS = 30 * 60_000;
+
+/** Is a process with this pid alive? EPERM means alive but not ours. Never throws. */
+export function pidAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}
+const seqOf = (name) => Number((/(\d{12})\.json$/.exec(name) || [])[1] ?? 0);
+const swarmEntries = (projectDir) => { try { return fs.readdirSync(path.join(projectDir, '.swarm')); } catch { return []; } };
+// 4.4.0 named queue files by wall clock: `<prefix><15-digit ms>-<hrtime>-<pid>-<n>.json`. Open 4.4.0
+// sessions keep queuing in that format after the update, so the two formats coexist for a while.
+const LEGACY_QUEUE = /^\d{15}-/;
+const queueTail = (name) => (name.startsWith(QUEUE_PREFIX) ? name.slice(QUEUE_PREFIX.length) : name.slice(CLAIM_PREFIX.length).replace(/^\d+-[A-Za-z0-9]*-\d+-/, ''));   // <pid>-<start>-<queuedAt>-
+const mtimeOf = (projectDir, name) => { try { return fs.statSync(path.join(projectDir, '.swarm', name)).mtimeMs; } catch { return Infinity; } };
+
+/**
+ * Queue one boundary's capture for the worker (0600, inside the project's own .swarm). ORDER IS THE
+ * ORDER OF EXCLUSIVE CREATION: the name is the next sequence number after every queued or claimed one,
+ * created with O_EXCL and retried on collision — never a clock, which can step backwards or wrap.
+ */
+export function queueCapture({ projectDir, event, host, payload }) {
+  const body = JSON.stringify({ event, host, payload });
+  for (let attempt = 0; attempt < 64; attempt += 1) {
+    const seq = Math.max(0, ...swarmEntries(projectDir).filter((n) => n.startsWith(QUEUE_PREFIX) || n.startsWith(CLAIM_PREFIX)).map(seqOf)) + 1;
+    const file = path.join(projectDir, '.swarm', `${QUEUE_PREFIX}${String(seq).padStart(12, '0')}.json`);
+    try { fs.writeFileSync(file, body, { flag: 'wx', mode: 0o600 }); return file; } catch (error) {
+      if (error?.code !== 'EEXIST') return null;
+    }
+  }
+  return null;
+}
 
-  let produced;
+/**
+ * Unclaimed queued captures, in queue order. While any 4.4.0 (timestamp-named) entry is present the
+ * order is creation time (mtime, then name) — by NAME every 4.4.1 sequence file would sort before every
+ * 4.4.0 one, replaying newer captures before older ones across the upgrade window. Once the legacy
+ * entries are gone the order is the sequence alone, independent of any clock.
+ */
+export function queuedCaptures(projectDir) {
+  const all = swarmEntries(projectDir).filter((n) => (n.startsWith(QUEUE_PREFIX) || n.startsWith(CLAIM_PREFIX)) && n.endsWith('.json'));
+  const queued = all.filter((n) => n.startsWith(QUEUE_PREFIX));
+  const mixed = all.some((n) => LEGACY_QUEUE.test(queueTail(n)));
+  const ordered = mixed
+    ? queued.map((n) => [mtimeOf(projectDir, n), n]).sort((a, b) => a[0] - b[0] || (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0)).map(([, n]) => n)
+    : queued.sort();
+  return ordered.map((n) => path.join(projectDir, '.swarm', n));
+}
+
+/** All older work a boundary must wait behind: unclaimed captures plus captures a worker has claimed. */
+export function queuedWork(projectDir) {
+  return swarmEntries(projectDir).filter((n) => (n.startsWith(QUEUE_PREFIX) || n.startsWith(CLAIM_PREFIX)) && n.endsWith('.json')).length;
+}
+
+/**
+ * A process's START TIME, as a filename-safe token, or null where it cannot be read (no `ps`, e.g.
+ * Windows). With the pid it identifies the process: a reused pid has a different start time.
+ */
+export function processStart(pid) {
   try {
-    produced = produce({ resolution, payload, host, trigger: event });
-  } catch (error) {
-    return { ...idle, replayed, skipped: `producer failed: ${error.message}` };
+    // TZ and locale PINNED: `lstart` prints local time in the locale's format, so two workers with
+    // different settings would record the same live process differently and read it as pid reuse.
+    const r = spawnSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000, windowsHide: true,
+      env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' } });
+    const s = String(r.stdout || '').replace(/[^A-Za-z0-9]/g, '');
+    return r.status === 0 && s ? s : null;
+  } catch { return null; }
+}
+let selfStart;
+const ownStart = () => (selfStart === undefined ? (selfStart = processStart(process.pid)) : selfStart);
+
+/**
+ * Claim a queued capture by atomic rename; null if taken. The claim's name records pid, start time and
+ * the queue file's ORIGINAL mtime (its creation order, which the mixed upgrade window sorts by); the
+ * claim file's own mtime is then set to the claim time, from which the orphan ceiling counts.
+ */
+function claimQueued(file) {
+  let queuedAt = 0;
+  try { queuedAt = Math.floor(fs.statSync(file).mtimeMs); } catch { return null; }
+  const claimed = path.join(path.dirname(file), `${CLAIM_PREFIX}${process.pid}-${ownStart() || 'na'}-${queuedAt}-${path.basename(file).slice(QUEUE_PREFIX.length)}`);
+  try { fs.renameSync(file, claimed); } catch { return null; }
+  try { const t = new Date(); fs.utimesSync(claimed, t, t); } catch { /* the ceiling then counts from queue time: earlier, never later */ }
+  return claimed;
+}
+const unclaimedName = (claimed) => path.join(path.dirname(claimed), `${QUEUE_PREFIX}${queueTail(path.basename(claimed))}`);
+/** Put a claim back in the queue: rename (atomic, needs no hard links), restoring its creation order. */
+const returnClaim = (claimed) => {
+  const queuedAt = Number(path.basename(claimed).slice(CLAIM_PREFIX.length).split('-')[2]);
+  const back = unclaimedName(claimed);
+  try { fs.renameSync(claimed, back); } catch { return false; }
+  if (Number.isFinite(queuedAt) && queuedAt > 0) { try { const t = new Date(queuedAt); fs.utimesSync(back, t, t); } catch { /* best effort */ } }
+  return true;
+};
+
+/**
+ * Return to the queue every claim whose worker is gone: its pid is dead, OR the pid now belongs to a
+ * different process (start time differs — pid reuse), OR the claim is older than REPLAY_LOCK_ABANDON_MS
+ * whatever the pid says (a reused pid where no start time can be read, a wedged worker). Without the
+ * last two a reused pid stranded a claim forever and every Stop spawned a worker that could not run it.
+ */
+export function reclaimOrphans(projectDir, { isAlive = pidAlive, startOf = processStart, now = Date.now() } = {}) {
+  let n = 0;
+  for (const name of swarmEntries(projectDir).filter((x) => x.startsWith(CLAIM_PREFIX))) {
+    const [pidText, start] = name.slice(CLAIM_PREFIX.length).split('-');
+    const pid = Number(pidText);
+    const claimed = path.join(projectDir, '.swarm', name);
+    const abandoned = now - mtimeOf(projectDir, name) > REPLAY_LOCK_ABANDON_MS;
+    let gone = abandoned || !isAlive(pid);
+    if (!gone && start && start !== 'na') {
+      const current = startOf(pid);
+      gone = Boolean(current) && current !== start;
+    }
+    if (gone && returnClaim(claimed)) n += 1;
   }
-  if (produced.skipped) return { ...idle, replayed, skipped: produced.skipped.reason };
+  return n;
+}
+
+const lockFacts = (file) => { const st = fs.statSync(file); return { content: fs.readFileSync(file, 'utf8'), mtimeMs: st.mtimeMs, ino: st.ino }; };
+const sameFacts = (a, b) => a.content === b.content && a.mtimeMs === b.mtimeMs && a.ino === b.ino;
+/** The pid ACTUALLY holding a lock: the `pid <n>` line a worker writes for itself, else the token's pid. */
+const holderPid = (content) => {
+  const line = /^pid (\d+)$/m.exec(String(content));
+  return Number(line ? line[1] : String(content).trim().split('-')[0]);
+};
 
-  let result;
+/**
+ * Take the lock. Returns this holder's TOKEN (`<pid>-<time>-<random>`), or null.
+ *  • Free → exclusive create.
+ *  • Fresh (refreshed within REPLAY_LOCK_STALE_MS) → null.
+ *  • Stale but its holder pid is ALIVE → null until REPLAY_LOCK_ABANDON_MS: a laptop asleep mid-step,
+ *    or a long step, is not a dead worker, and taking over would put two workers on one job. The holder
+ *    pid is the WORKER's own (it rewrites the lock on start), not the hook that spawned it and exited.
+ *  • Otherwise taken over: the stale file is renamed aside and VERIFIED to be the very file judged
+ *    stale (content, mtime, inode). If a successor's fresh lock was moved instead (it took over between
+ *    our check and our rename), it is put back — never over a third lock — and we back off. One winner.
+ */
+export function takeReplayLock(projectDir, now = Date.now(), { isAlive = pidAlive, beforeRename = null } = {}) {
+  const lock = lockPath(projectDir);
+  const token = `${process.pid}-${now}-${Math.random().toString(36).slice(2, 10)}`;
+  const create = () => { fs.writeFileSync(lock, `${token}\npid ${process.pid}\n`, { flag: 'wx', mode: 0o600 }); return token; };
+  try { return create(); } catch { /* held, or stale */ }
+  let seen;
+  try { seen = lockFacts(lock); } catch { try { return create(); } catch { return null; } }
+  const age = now - seen.mtimeMs;
+  if (age <= REPLAY_LOCK_STALE_MS) return null;
+  if (age <= REPLAY_LOCK_ABANDON_MS && isAlive(holderPid(seen.content))) return null;
+  beforeRename?.();
+  const aside = `${lock}.stale-${token}`;
+  try { fs.renameSync(lock, aside); } catch { return null; }
+  let moved = null;
+  try { moved = lockFacts(aside); } catch { /* vanished */ }
+  if (!moved || !sameFacts(moved, seen)) {
+    // Put the successor's lock back without ever overwriting a third holder's: a hard link where the
+    // filesystem has them, else an exclusive copy.
+    try { fs.linkSync(aside, lock); } catch {
+      try { fs.copyFileSync(aside, lock, fs.constants.COPYFILE_EXCL); } catch { /* a third holder exists; the successor sees it lost the lock and stops */ }
+    }
+    try { fs.rmSync(aside, { force: true }); } catch { /* best effort */ }
+    return null;
+  }
+  try { fs.rmSync(aside, { force: true }); } catch { /* best effort */ }
+  try { 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; }
+}
+
+/** A worker that inherited the lock records ITS OWN pid on it, keeping the owner token. */
+export function adoptReplayLock(projectDir, token) {
+  if (!token || readLock(projectDir) !== token) return false;
+  try { fs.writeFileSync(lockPath(projectDir), `${token}\npid ${process.pid}\n`, { mode: 0o600 }); 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 {
-    result = captureProgression({
-      host,
-      payload: { ...payload, hook_event_name: event, projectProgression: produced.projectProgression },
-      projectDir,
-      storeFactory,
+    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`: record its own pid on the lock, return orphaned
+ * claims to the queue, replay the outbox, then run every queued capture IN ORDER — each CLAIMED by
+ * atomic rename first, so no other worker can run it too, and each re-entering the boundary as
+ * `ordered`, so it replays before it produces. Ownership is re-checked before every step and right
+ * after each claim; a worker that lost the lock puts an unstarted claim back and stops. A finished
+ * claim is the claimer's own and is deleted. 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, onClaim = null } = {}) {
+  let held = token || takeReplayLock(projectDir);
+  let replayed = 0;
+  for (let round = 0; held && round < 8; round += 1) {
+    try {
+      if (!adoptReplayLock(projectDir, held)) return replayed;
+      reclaimOrphans(projectDir);
+      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;
+        const claimed = claimQueued(file);
+        if (!claimed) continue;
+        onClaim?.(claimed);
+        if (!refreshReplayLock(projectDir, held)) {
+          returnClaim(claimed);
+          return replayed;
+        }
+        let job = null;
+        try { job = JSON.parse(fs.readFileSync(claimed, '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(claimed, { force: true }); } catch { /* best effort */ }
+      }
+    } catch { /* the debt stays durable; the next boundary hands it on again */ } finally {
+      releaseReplayLock(projectDir, held);
+    }
+    held = queuedWork(projectDir) ? 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;
       }