ruvnet-brain 4.4.0 → 4.5.0

package/plugin/scripts/project-progression-store.mjs

@@ -180,6 +180,145 @@ export function rufloCwdFor(storePath, { root = rufloScratchRoot() } = {}) {
   return ensurePrivateDir(path.join(root, projectKey));
 }
 
+/**
+ * 4.3.40 ran ruflo with cwd `<project>/.swarm`, so upgraded projects still hold ruflo's cwd artifacts
+ * INSIDE the store directory — including `.swarm/.swarm/hnsw.metadata.json`, a copy of snapshot content.
+ * Removes exactly those, and only when every path in them is one ruflo is known to write there; anything
+ * unexpected (or any symlink) leaves that artifact untouched and is REPORTED. The store itself
+ * (memory.db, -wal/-shm, schema.sql), the outbox and queue files are never candidates.
+ *
+ * The allowlist is measured, not guessed: real ruflo 3.49.0 run with cwd=<dir> and --path elsewhere
+ * writes .claude/{memory.db,.proven-config-version,proven-config.json} (init/store),
+ * .claude-flow/harness-active-policy.json and .swarm/{hnsw.index,hnsw.metadata.json} and ruvector.db
+ * (store), .claude-flow/policy/state.json (retrieve). The owner's real 4.3.40 projects also hold
+ * .swarm/.swarm/agentdb-memory.db(-wal,-shm): ruflo's AgentDB bridge opens <cwd>/.swarm/agentdb-memory.db
+ * (ruflo/v3/@claude-flow/cli/src/memory/memory-bridge.ts getAgentDbPath), and the native bindings drop
+ * ruvector.db into whatever cwd they run in (ruflo/scripts/smoke-memory-no-stray-db.mjs, ADR-125 Phase 7).
+ */
+const SQLITE = (name) => [name, `${name}-wal`, `${name}-shm`, `${name}-journal`];
+const LEGACY_CWD_ARTIFACTS = Object.freeze({
+  '.swarm': new Set(['hnsw.index', 'hnsw.metadata.json', ...SQLITE('agentdb-memory.db')]),
+  '.claude': new Set(['.proven-config-version', 'proven-config.json', ...SQLITE('memory.db')]),
+  '.claude-flow': new Set(['harness-active-policy.json', 'policy/', 'policy/state.json']),
+  'ruvector.db': null, // a regular file
+});
+
+/** Every path under `dir`, relative, directories with a trailing slash; symlinks reported, never followed. */
+function relativeEntries(dir) {
+  const out = [];
+  const walk = (current, prefix) => {
+    for (const name of fs.readdirSync(current)) {
+      const full = path.join(current, name);
+      const stat = fs.lstatSync(full);
+      const rel = prefix + name;
+      if (stat.isSymbolicLink()) out.push({ rel, link: true });
+      else if (stat.isDirectory()) { out.push({ rel: `${rel}/` }); walk(full, `${rel}/`); }
+      else out.push({ rel, file: stat.isFile() });
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+/**
+ * With `dryRun`, reports what WOULD be removed and touches nothing (--doctor). Returns
+ * { removed: [paths], refused: [{ path, reason }] }; a refusal must be shown to the user, never dropped.
+ */
+const IN_USE_MS = 10 * 60_000;
+// The files that carry DATA: the database, its WAL and its rollback journal. Never -shm: it is the WAL
+// index, and every reader — including this proof's own read-only open — rewrites it. Counting it made
+// every real 4.3.40 store look "changed while it was being checked" (and "in use" on the next run).
+const dataFiles = (dbPath) => {
+  const base = path.basename(dbPath);
+  return [base, `${base}-wal`, `${base}-journal`];
+};
+const sqliteFingerprint = (dbPath) => dataFiles(dbPath).map((name) => {
+  try { const st = fs.statSync(path.join(path.dirname(dbPath), name)); return `${name}:${st.size}:${st.mtimeMs}`; }
+  catch { return `${name}:absent`; }
+});
+const sameFiles = (a, b) => a.join('|') === b.join('|');
+
+/**
+ * Is every active (namespace, key, content) row of a stray nested AgentDB present, byte-identical, in
+ * the canonical store? Read-only through the progression reader (node:sqlite, readOnly — no write, no
+ * checkpoint). Anything it cannot prove — recently written (in use), unreadable, a row missing or
+ * different — keeps the file and says why.
+ */
+export function proveMirrored(nestedDb, canonicalDb, { now = Date.now(), maxRows = 100_000 } = {}) {
+  const fingerprint = sqliteFingerprint(nestedDb);
+  const newest = Math.max(...dataFiles(nestedDb).map((name) => {
+    try { return fs.statSync(path.join(path.dirname(nestedDb), name)).mtimeMs; } catch { return 0; }
+  }));
+  if (now - newest < IN_USE_MS) return { ok: false, reason: `kept: agentdb-memory.db was written ${Math.round((now - newest) / 1000)}s ago (in use)` };
+  const nested = withProgressionReader(nestedDb, (reader) => reader.allRows({ maxRows }));
+  if (!nested.ok) return { ok: false, reason: `kept: agentdb-memory.db could not be read to prove it is mirrored (${nested.reason})` };
+  const canonical = withProgressionReader(canonicalDb, (reader) => reader.allRows({ maxRows }));
+  if (!canonical.ok) return { ok: false, reason: `kept: memory.db could not be read to prove agentdb-memory.db is mirrored (${canonical.reason})` };
+  const have = new Map(canonical.value.map((row) => [`${row.namespace}\u0000${row.key}`, row.content]));
+  const missing = nested.value.filter((row) => row.content === null || have.get(`${row.namespace}\u0000${row.key}`) !== row.content);
+  if (missing.length) return { ok: false, reason: `kept: ${missing.length} of ${nested.value.length} rows not in memory.db`, missing: missing.length };
+  return { ok: true, rows: nested.value.length, fingerprint };
+}
+
+export function cleanLegacyRufloDebris(storeDir, { dryRun = false, now = Date.now() } = {}) {
+  const removed = [];
+  const refused = [];
+  for (const [name, allowed] of Object.entries(LEGACY_CWD_ARTIFACTS)) {
+    const entry = path.join(storeDir, name);
+    let stat;
+    try { stat = fs.lstatSync(entry); } catch { continue; } // absent: nothing to do
+    if (stat.isSymbolicLink()) { refused.push({ path: entry, reason: 'symbolic link' }); continue; }
+    if (allowed === null) {
+      if (!stat.isFile()) { refused.push({ path: entry, reason: 'not a regular file' }); continue; }
+    } else {
+      if (!stat.isDirectory()) { refused.push({ path: entry, reason: 'not a directory' }); continue; }
+      const unknown = relativeEntries(entry).filter((item) => item.link || item.file === false || !allowed.has(item.rel))
+        .map((item) => (item.link ? `${item.rel} (symbolic link)` : item.rel));
+      if (unknown.length) { refused.push({ path: entry, reason: `unexpected entries: ${unknown.join(', ')}` }); continue; }
+    }
+    // A nested AgentDB is a real store (owner's projects: 1-41 rows, still written by open 4.3.40
+    // sessions). It goes only when every row is PROVEN present, identically, in the canonical memory.db.
+    const nestedDb = path.join(entry, 'agentdb-memory.db');
+    const mirror = name === '.swarm' && fs.existsSync(nestedDb) ? proveMirrored(nestedDb, path.join(storeDir, 'memory.db'), { now }) : null;
+    if (mirror && !mirror.ok) { refused.push({ path: entry, reason: mirror.reason, kept: true }); continue; }
+    if (!dryRun) {
+      // The proof is only valid for the bytes it read: anything written since means the file is in use.
+      if (mirror && !sameFiles(mirror.fingerprint, sqliteFingerprint(nestedDb))) {
+        refused.push({ path: entry, reason: 'kept: agentdb-memory.db changed while it was being checked (in use)', kept: true });
+        continue;
+      }
+      fs.rmSync(entry, { recursive: true, force: true });
+    }
+    removed.push(entry);
+  }
+  return { removed, refused };
+}
+
+// What ruflo leaves in a cwd (measured, ruflo 3.49.0): `.swarm/` (hnsw.index, hnsw.metadata.json — a
+// copy of every stored value), `.claude/`, `.claude-flow/`, `ruvector.db`. None of it is read back by the
+// product: every call carries --path, and the store of record is that file.
+const RUFLO_CWD_ARTIFACTS = Object.freeze(['.swarm', '.claude', '.claude-flow', 'ruvector.db']);
+const STALE_RUN_MS = 3_600_000;
+
+/**
+ * One ruflo invocation's working directory: a fresh private `run-*` directory inside the project's
+ * scratch dir, removed again by the caller after the call. ruflo copies every snapshot it touches into
+ * `<cwd>/.swarm/hnsw.metadata.json`; with one cwd per call that copy never accumulates (4.4.0 kept one
+ * per project that grew without bound and outlived the project). Also clears what 4.4.0 left directly
+ * in the project scratch dir and any `run-*` older than an hour (a call killed before its cleanup).
+ */
+export function rufloRunDir(storePath, { root = rufloScratchRoot(), now = Date.now() } = {}) {
+  const projectScratch = rufloCwdFor(storePath, { root });
+  for (const name of fs.readdirSync(projectScratch)) {
+    const entry = path.join(projectScratch, name);
+    let stat;
+    try { stat = fs.lstatSync(entry); } catch { continue; }
+    const stale = name.startsWith('run-') && stat.isDirectory() && now - stat.mtimeMs > STALE_RUN_MS;
+    if (RUFLO_CWD_ARTIFACTS.includes(name) || stale) fs.rmSync(entry, { recursive: true, force: true });
+  }
+  return fs.mkdtempSync(path.join(projectScratch, 'run-'));
+}
+
 export class ProjectProgressionStore {
   constructor({
     projectDir,
@@ -194,6 +333,9 @@ export class ProjectProgressionStore {
   } = {}) {
     if (!rufloBinary) throw new Error(RUFLO_MISSING);
     this.resolution = resolveProjectStore({ projectDir, requestedStorePath });
+    // Best effort: a cleanup that cannot run must never stop a capture or a restore.
+    try { this.legacyDebris = cleanLegacyRufloDebris(path.dirname(this.resolution.canonicalAgentDbPath)); }
+    catch (error) { this.legacyDebris = { removed: [], refused: [{ path: null, reason: error.message }] }; }
     this.rufloBinary = rufloBinary;
     this.runner = runner;
     this.clock = clock;
@@ -212,12 +354,17 @@ export class ProjectProgressionStore {
   }
 
   run(args) {
-    return this.runner(this.rufloBinary, args, {
-      cwd: rufloCwdFor(this.resolution.canonicalAgentDbPath),
-      encoding: 'utf8',
-      timeout: 120_000,
-      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
-    });
+    const cwd = rufloRunDir(this.resolution.canonicalAgentDbPath);
+    try {
+      return this.runner(this.rufloBinary, args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: 120_000,
+        env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
+      });
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
   }
 
   validateSnapshot(snapshot) {

package/plugin/scripts/protect-brain-state.sh

@@ -52,7 +52,10 @@ INPUT="${INPUT:0:65536}"
 
 field() { local re="\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""; [[ $INPUT =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"; }
 
-case "$(field tool_name)" in Write|Edit|MultiEdit|NotebookEdit) ;; *) exit 0 ;; esac
+# Case-insensitive (4.5): Grok sends its own spelling (`write`, `search_replace`) — a case-sensitive
+# match let a Grok write past this guard silently. nocasematch is scoped to this one test.
+shopt -s nocasematch
+case "$(field tool_name)" in Write|Edit|MultiEdit|NotebookEdit|search_replace|multi_edit) shopt -u nocasematch ;; *) exit 0 ;; esac
 
 FILE_PATH=$(field file_path)
 [ -n "$FILE_PATH" ] || exit 0

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

@@ -13,6 +13,7 @@ import { buildProjectProgression } from './project-progression-producer.mjs';
 import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { captureTurnOutcome } from './turn-outcome-capture.mjs';
+import { captureContinuityEvents, stopNotice } from './continuity-journal.mjs';
 
 /**
  * The capture boundary's whole budget. hooks.json declares 10s; this keeps the internal work well
@@ -122,6 +123,7 @@ export function runSessionSnapshotHook(projectDir, event, {
   makeStoreFactory = boundedStoreFactory,
   spawnReplay = replayOutboxDetached,
   ordered = null,
+  captureEvents = captureContinuityEvents,
 } = {}) {
   // The detached worker re-runs a QUEUED boundary; its session receipt was already written then.
   const metadataWritten = writeMetadata ? writeSessionSnapshot(projectDir, event) : false;
@@ -134,7 +136,14 @@ export function runSessionSnapshotHook(projectDir, event, {
   try { turn = captureTurn({ projectDir, event, payload, host }); } catch (error) {
     turn = { recorded: false, skipped: `turn capture failed: ${error.message}` };
   }
-  const idle = { metadataWritten, progressionCaptured: false, receipt: null, turn };
+  // MATERIAL EVENTS (continuity-journal.mjs): commits, releases, gates, findings, decisions, lessons —
+  // journalled to the durable outbox with one fsync and committed by a detached drainer. Like turn
+  // capture it is independent of the progression lock below and costs this boundary only a read.
+  let continuity;
+  try { continuity = captureEvents({ projectDir, event, payload, host }); } catch (error) {
+    continuity = { recorded: 0, skipped: `continuity capture failed: ${error.message}` };
+  }
+  const idle = { metadataWritten, progressionCaptured: false, receipt: null, turn, continuity };
 
   if (hasProjectProgression(payload)) {
     if (payload.hook_event_name !== event) {
@@ -183,12 +192,12 @@ export function runSessionSnapshotHook(projectDir, event, {
     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)') : ''}` };
+        + `${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 = queuedCaptures(root).length;
+    const queuedAhead = queuedWork(root);
     if (queuedAhead) return handOff(`${queuedAhead} older capture(s) queued`);
     if (budgetMs < REPLAY_MIN_BUDGET_MS) {
       const pending = pendingCount();
@@ -207,6 +216,14 @@ export function runSessionSnapshotHook(projectDir, event, {
       } 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 });
@@ -235,12 +252,22 @@ export function runSessionSnapshotHook(projectDir, event, {
       metadataWritten,
       progressionCaptured: true,
       turn,
+      continuity,
       replayed,
       receipt: result.receipt,
       provenance: produced.provenance,
     };
   } finally {
-    if (!ordered && !handedLock) releaseReplayLock(root, token);
+    // 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 });
+      }
+    }
   }
 }
 
@@ -253,44 +280,171 @@ 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;
+// 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;
 
-/** 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 {
-    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; }
+/** 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;
+}
+
+/**
+ * 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 {
-    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 []; }
+    // 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;
+  }
+  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]);
+};
+
 /**
- * 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.
+ * 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()) {
+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}\n`, { flag: 'wx', mode: 0o600 }); return token; };
+  const create = () => { fs.writeFileSync(lock, `${token}\npid ${process.pid}\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; }
+  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. */
@@ -299,6 +453,12 @@ export function refreshReplayLock(projectDir, token) {
   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;
@@ -323,19 +483,22 @@ export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn
 }
 
 /**
- * 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
+ * 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 } = {}) {
+  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 (!refreshReplayLock(projectDir, held)) return replayed;
+      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()) {
@@ -345,19 +508,27 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
       }
       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(file, 'utf8')); } catch { /* torn: dropped below */ }
+        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' }) });
+            captureTurn: () => ({ recorded: false, skipped: 'detached replay' }),
+            captureEvents: () => ({ recorded: 0, skipped: 'detached replay' }) });
         } catch { /* a failed capture leaves its own snapshot durable in the outbox */ }
-        try { fs.rmSync(file, { force: true }); } catch { /* best effort */ }
+        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 = queuedCaptures(projectDir).length ? takeReplayLock(projectDir) : null;
+    held = queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
   }
   return replayed;
 }
@@ -369,7 +540,20 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-
   // independently is what let this hook write a receipt the Console then reported as missing (#85).
   const rawInput = fs.readFileSync(0, 'utf8');
   try {
-    runSessionSnapshotHook(projectDirectory(), process.argv[2] || 'SessionEnd', { rawInput });
+    const result = runSessionSnapshotHook(projectDirectory(), process.argv[2] || 'SessionEnd', { rawInput });
+    // FAIL LOUDLY, NEVER SILENTLY — AND ONCE. When recording is stuck (events pending past STUCK_AFTER_MS,
+    // a quarantined conflict, a corrupt outbox line, a cap drop) Claude Code shows this systemMessage, at
+    // most once per session per condition (stopNotice; it used to repeat at every turn). "Not applicable"
+    // (no store, no ruflo) is never stuck. Codex is excluded on purpose: its Stop schema turns any `reason`
+    // into a BLOCK (codex-hook-adapter.mjs), and a recording problem must never hold a turn open.
+    const host = process.env.RUVNET_HOOK_HOST || 'claude';
+    const { status, journal } = result?.continuity || {};
+    if (host === 'claude' && status?.stuck && journal) {
+      let session = null;
+      try { session = JSON.parse(rawInput || '{}').session_id || null; } catch { /* no session: still once per 'unknown' */ }
+      const message = stopNotice({ journal, status, session });
+      if (message) process.stdout.write(JSON.stringify({ systemMessage: message }));
+    }
   } catch (error) {
     // ADVISORY, ALWAYS. A capture boundary fires at Stop, PreCompact and SessionEnd; one that can
     // return a non-zero status can interrupt a turn, a compaction, or a clean exit. Report and exit 0.

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

@@ -43,6 +43,7 @@ export const STAGE_BUDGETS_MS = {
   'signal-surface': 400,  // bounded CI-signal transition poll (see session-start-signals.mjs)
   'router-nudge': 50,     // one fs.existsSync + at-most-one-time write
   'knowledge-currency': 100, // refresh receipts + registration + SOURCE.json reads; no spawn, no network
+  footprint: 150,         // name-only classification (measured ~20ms on a 1.4 GB brain) + at-most-one detach launch
   'stable-spine': 300,    // seed-dispatch decision + a single detach launch
   heartbeat: 300,         // update-check dispatch launch
   'ascii-drift': 300,     // optional ascii->svg drift advisory, already spawnSync-timeout bounded