ruvnet-brain 4.5.3 → 4.5.4

package/plugin/scripts/project-capture-queue.mjs

@@ -0,0 +1,333 @@
+/** Canonical capture queue, fencing and bounded replay; no independent writer authority. */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { developmentHooksSuspended } from './development-maintenance.mjs';
+import { resolveTurnDb } from './turn-outcome-capture.mjs';
+import { buildProjectProgression } from './project-progression-producer.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { redactProgression } from './project-progression-contract.mjs';
+import { ProgressionOutbox } from './project-progression-outbox.mjs';
+import { captureNormalizedTransition } from './project-transition-hook.mjs';
+import { boundedStoreFactory, runSessionSnapshotHook } from './session-snapshot-hook.mjs';
+
+/**
+ * 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, originProjectDir = projectDir, event, host, payload, env = process.env }) {
+  try {
+    const consent = resolveTurnDb({ projectDir: originProjectDir, requestedStorePath: path.join(projectDir, '.swarm', 'memory.db'),
+      brainHome: env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain') });
+    if (consent.skipped) return null;
+  } catch { return null; }
+  // Freeze legacy callers at the original boundary too, before dropping host payload.
+  let progression = payload?.projectProgression;
+  if (!progression && !payload?.normalizedTransition) {
+    try { progression = buildProjectProgression({ resolution: resolveProjectStore({ projectDir: originProjectDir }), projectDir: originProjectDir, payload, host, trigger: event }).projectProgression; } catch { return null; }
+  }
+  // This queue is durable: never serialize arbitrary host prompts, tool input or output.
+  const minimized = { session_id: payload?.session_id, hook_event_name: event,
+    ...(progression ? { projectProgression: progression } : {}),
+    ...(payload?.normalizedTransition ? { normalizedTransition: payload.normalizedTransition } : {}) };
+  const body = JSON.stringify(redactProgression({ event, host, originProjectDir,
+    queuedAt: new Date().toISOString(), payload: minimized }).value);
+  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 {
+      const fd = fs.openSync(file, 'wx', 0o600);
+      try { fs.writeFileSync(fd, body); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+      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 {
+    // 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 (`<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 {
+    const child = spawnFn(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'session-snapshot-hook.mjs'), '--replay-outbox'], {
+      cwd: projectDir, detached: true, stdio: 'ignore', windowsHide: true,
+      env: { ...process.env, RUVNET_REPLAY_LOCK_TOKEN: held },
+    });
+    child.unref?.();
+    return true;
+  } catch {
+    releaseReplayLock(projectDir, held);
+    return false;
+  }
+}
+
+/**
+ * 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,
+  captureNormalized = captureNormalizedTransition, onCaptured = null } = {}) {
+  const deadlineAt = now() + budgetMs;
+  if (developmentHooksSuspended(projectDir)) return 0;
+  const brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
+  try {
+    const consent = resolveTurnDb({ projectDir, brainHome });
+    if (consent.skipped && !consent.skipped.startsWith('no project memory db')) return 0;
+  } catch { return 0; }
+  let held = token || takeReplayLock(projectDir);
+  let replayed = 0;
+  for (let round = 0; held && round < 8 && now() < deadlineAt; round += 1) {
+    try {
+      if (!adoptReplayLock(projectDir, held)) return replayed;
+      reclaimOrphans(projectDir);
+      const resolution = resolveProjectStore({ projectDir });
+      const store = makeStoreFactory(deadlineAt)({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath });
+      for (const snapshot of store.outbox.pendingSnapshots()) {
+        if (now() >= deadlineAt) return replayed;
+        if (!refreshReplayLock(projectDir, held)) return replayed;
+        store.outbox.markCommitted(store.appendExact(snapshot));
+        replayed += 1;
+      }
+      for (const file of queuedCaptures(projectDir)) {
+        if (now() >= deadlineAt) return replayed;
+        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 */ }
+        let committed = false;
+        try {
+          if (job) {
+            // Pre-upgrade raw queues lack origin identity and cannot be truthfully reconstructed.
+            if (runCapture === runSessionSnapshotHook && (!job.originProjectDir || (!job.payload?.projectProgression && !job.payload?.normalizedTransition))) { returnClaim(claimed); return replayed; }
+            const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome });
+            if (developmentHooksSuspended(job.originProjectDir || projectDir)
+              || (consent.skipped && !consent.skipped.startsWith('no project memory db'))) { returnClaim(claimed); return replayed; }
+            const options = { rawInput: JSON.stringify(job.payload), host: job.host,
+              budgetMs: Math.max(0, deadlineAt - now()), makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
+              captureTurn: () => ({ recorded: false, skipped: 'detached replay' }),
+              captureEvents: () => ({ recorded: 0, skipped: 'detached replay' }) };
+            const result = job.payload?.normalizedTransition ? captureNormalized(job, options)
+              : runCapture(job.originProjectDir || projectDir, job.event, options);
+            committed = result?.progressionCaptured === true && Boolean(result.receipt);
+            if (committed) onCaptured?.(result);
+          }
+        } catch { /* retain the queue until an exact-readback receipt exists */ }
+        if (!committed) { returnClaim(claimed); return replayed; }
+        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 = now() < deadlineAt && queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
+  }
+  if (held) releaseReplayLock(projectDir, held);
+  return replayed;
+}
+
+
+/** Synchronous bounded startup drain. Pending debt must downgrade restore, never disappear. */
+export function drainCaptureQueue({ projectDir, budgetMs = 1000, ...options } = {}) {
+  const startedAt = Date.now();
+  const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)) });
+  const root = resolution.projectRoot;
+  const replayed = runOutboxReplay({ ...options, projectDir: root, budgetMs: Math.max(0, budgetMs - (Date.now() - startedAt)) });
+  let outboxPending = 0;
+  try { outboxPending = new ProgressionOutbox({ projectRoot: root }).pendingSnapshots().length; } catch { return { state: 'degraded', replayed, pending: null }; }
+  const pending = queuedWork(root) + outboxPending;
+  return { state: pending ? 'pending' : 'settled', replayed, pending };
+}
+

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

@@ -304,7 +304,7 @@ function mergeHeads(heads) {
       ...heads[0].completeProjectState,
       sourceIdentity: heads[0].sourceIdentity,
       journalHeads: [heads[0].eventKey],
-      resumeConflicts: [],
+      resumeConflicts: heads[0].completeProjectState.resumeConflicts,
     });
   }
 

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

@@ -63,7 +63,7 @@ export function readProgressionAdapterVersion() {
   return requireString(parsed?.version, 'progression adapter version');
 }
 
-function normalizeSourceIdentity(value, checkoutRoot) {
+function normalizeSourceIdentity(value, checkoutRoot, projectDir) {
   requireRecord(value, 'sourceIdentity');
   const checkoutPath = requireString(value.checkoutPath, 'sourceIdentity.checkoutPath');
   let canonicalCheckout;
@@ -73,7 +73,7 @@ function normalizeSourceIdentity(value, checkoutRoot) {
   if (canonicalCheckout !== checkoutRoot) {
     throw new Error('source identity checkout path does not match the active checkout path');
   }
-  return { ...value, checkoutPath: canonicalCheckout };
+  return { ...value, checkoutPath: canonicalCheckout, capturePath: fs.realpathSync.native(projectDir) };
 }
 
 const OBSERVATION_TEXT_LIMIT = 4_096;
@@ -189,7 +189,7 @@ export function captureProjectTransition({
 
   const sourceIdentity = normalizeSourceIdentity(
     aliased(progression, 'sourceIdentity', 'source_identity'),
-    store.resolution.checkoutRoot,
+    store.resolution.checkoutRoot, projectDir,
   );
   const snapshot = createProgressionSnapshot({
     projectIdentity: store.resolution.projectIdentity,

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

@@ -29,6 +29,7 @@
  * within those bounds.
  */
 import crypto from 'node:crypto';
+import fs from 'node:fs';
 import path from 'node:path';
 import { digestCanonical, fieldAuthorityAllows, redactProgression, restoreProjectProgression } from './project-progression-contract.mjs';
 import { readOwnerNote, readSourceIdentity, readTranscriptReference, readWorkLedger } from './project-progression-sources.mjs';
@@ -94,10 +95,14 @@ function committedHeads(canonicalAgentDbPath, projectIdentity) {
     }
     return snapshots;
   });
-  if (!result.ok) return { heads: [], readPath: `unavailable (${result.reason})` };
+  if (!result.ok) {
+    if (fs.existsSync(canonicalAgentDbPath)) throw new Error(`prior progression read unavailable: ${result.reason}`);
+    return { heads: [], state: null, readPath: `unavailable (${result.reason})` };
+  }
   const restored = restoreProjectProgression(result.value, { expectedProjectIdentity: projectIdentity });
+  if (result.value.length && !restored.ok) throw new Error('prior progression has no verifiable coherent state');
   const byKey = new Map(result.value.map((snapshot) => [snapshot?.eventKey, snapshot]));
-  return { heads: restored.heads.map((key) => byKey.get(key)).filter(Boolean), readPath: 'node:sqlite' };
+  return { heads: restored.heads.map((key) => byKey.get(key)).filter(Boolean), state: restored.state, readPath: 'node:sqlite' };
 }
 
 function uniqueStrings(values) {
@@ -115,6 +120,7 @@ function uniqueStrings(values) {
  */
 export function buildProjectProgression({
   resolution,
+  projectDir = resolution?.checkoutRoot,
   payload = {},
   host = 'claude',
   env = process.env,
@@ -123,20 +129,21 @@ export function buildProjectProgression({
 } = {}) {
   if (!resolution || typeof resolution !== 'object') throw new TypeError('resolution must be a project store resolution');
   const source = readSourceIdentity({ checkoutRoot: resolution.checkoutRoot, kind: resolution.kind });
+  source.identity.capturePath = fs.realpathSync.native(projectDir);
   const ledger = readWorkLedger({ projectId: resolution.projectIdentity.id, env });
   const note = readOwnerNote(() => ownerNoteRows(resolution.canonicalAgentDbPath, path.basename(resolution.projectRoot)));
   const transcript = readTranscriptReference(payload.transcript_path, { host });
-  const { heads } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity);
+  const { heads, state: priorState } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity);
 
   const priorSequence = heads.reduce((highest, head) => Math.max(highest, head.sequence ?? 0), 0);
-  const priorState = heads.length === 1 ? heads[0].completeProjectState : null;
 
-  const provenance = {};
+  const provenance = { ...(priorState?.provenance ?? {}) };
   const record = (field, sourceName) => {
     if (sourceName !== 'none' && !fieldAuthorityAllows(field === 'sourceIdentity' ? 'sourceIdentity' : field, sourceName)) {
       throw new Error(`source ${sourceName} is not authoritative for progression field ${field}`);
     }
-    provenance[field] = marker(sourceName);
+    provenance[field] = sourceName === 'prior-head' && priorState?.provenance?.[field]
+      ? priorState.provenance[field] : marker(sourceName);
   };
 
   // GOAL — the ledger's oldest open item is what the user actually committed to. A coherent prior
@@ -144,7 +151,7 @@ export function buildProjectProgression({
   // no durable goal exists. Neither contextual source is an instruction.
   let currentGoal = ledger.open[0] ?? null;
   if (currentGoal) record('currentGoal', 'ledger');
-  else if (typeof priorState?.currentGoal === 'string' && priorState.currentGoal) {
+  else if (priorState) {
     currentGoal = priorState.currentGoal;
     record('currentGoal', 'prior-head');
   } else if (note?.excerpt) {
@@ -159,12 +166,12 @@ export function buildProjectProgression({
   // Transcript text is evidence/context, never an invented structured action.
   let nextAction = ledger.open[1] ?? ledger.open[0] ?? null;
   if (nextAction) record('nextAction', 'ledger');
-  else if (typeof priorState?.nextAction === 'string' && priorState.nextAction) {
+  else if (priorState) {
     nextAction = priorState.nextAction;
     record('nextAction', 'prior-head');
   } else record('nextAction', 'none');
 
-  const decisions = [];
+  const decisions = [...(priorState?.decisions ?? [])];
   if (ledger.objective && typeof ledger.objective.text === 'string' && ledger.objective.text) {
     decisions.push({ text: ledger.objective.text, state: ledger.objective.state ?? null, source: 'ledger' });
     record('decisions', 'ledger');
@@ -173,31 +180,49 @@ export function buildProjectProgression({
     record('decisions', 'owner-note');
   } else record('decisions', 'prior-head');
 
-  record('plan', ledger.present ? 'ledger' : 'prior-head');
-  record('completed', ledger.present ? 'ledger' : 'prior-head');
-  record('inProgress', ledger.present ? 'ledger' : 'prior-head');
+  // A partial ledger speaks only for its own matching items; absence is not deletion.
+  const priorPlan = priorState?.plan ?? [];
+  const doneIds = new Set(ledger.done.map((text) => text.slice(0, 64)));
+  const openIds = new Set(ledger.open.map((text) => text.slice(0, 64)));
+  const ownedDone = new Set(priorPlan.filter((item) => item?.source === 'ledger' && doneIds.has(item.id)).map((item) => item.id));
+  const plan = priorPlan.map((item) => item?.source !== 'ledger' ? item
+    : doneIds.has(item.id) ? { ...item, status: 'done' }
+      : openIds.has(item.id) ? { ...item, status: 'open' } : item);
+  for (const text of ledger.open) {
+    const id = text.slice(0, 64);
+    if (!plan.some((item) => item?.source === 'ledger' && item.id === id)) plan.push({ id, status: 'open', source: 'ledger' });
+  }
+  const completed = [...(priorState?.completed ?? [])];
+  for (const text of ledger.done) if (!completed.includes(text)) completed.push(text);
+  const inProgress = uniqueStrings([...(priorState?.inProgress ?? []).filter((text) => !ownedDone.has(text.slice(0, 64))), ...ledger.open]);
+  for (const field of ['plan', 'completed', 'inProgress']) {
+    record(field, ledger.open.length || ledger.done.length ? 'ledger' : 'prior-head');
+    if (priorState && (ledger.open.length || ledger.done.length)) provenance[field] = { source: 'prior-head', authoritative: priorState.provenance?.[field]?.authoritative ?? true, sources: ['prior-head', 'ledger'] };
+  }
   record('changedFiles', 'git');
   record('sourceIdentity', 'git');
 
+  // Reducer annotations describe the prior heads, not application state in the new snapshot.
+  const { sourceIdentity: priorSource, journalHeads: priorHeads, ...carriedState } = priorState ?? {};
   const completeProjectState = {
+    ...carriedState,
     currentGoal,
     nextAction,
     acceptanceContract: priorState?.acceptanceContract ?? null,
-    activeProcess: 'ProjectContinuity',
-    activeStep: trigger ?? 'unknown',
-    plan: ledger.open.map((text) => ({ id: text.slice(0, 64), status: 'open', source: 'ledger' })),
-    completed: uniqueStrings(ledger.done),
-    inProgress: uniqueStrings(ledger.open),
-    blockers: [],
-    failures: [],
-    decisions,
-    // The three digests already identify the tree exactly; enumerating paths here would duplicate
-    // that and, for an untracked file, would put a filename we were never asked to keep into a row.
-    changedFiles: [],
-    commands: [],
-    proofArtifacts: [],
-    untested: [],
-    resumeConflicts: [],
+    activeProcess: priorState ? priorState.activeProcess : 'ProjectContinuity',
+    activeStep: priorState ? priorState.activeStep : trigger ?? 'unknown',
+    plan,
+    completed,
+    inProgress,
+    blockers: priorState?.blockers ?? [],
+    failures: priorState?.failures ?? [],
+    decisions: [...new Map(decisions.map((decision) => [digestCanonical(decision), decision])).values()],
+    // Retain previously recorded paths; the new tree's digests never invent additional filenames.
+    changedFiles: priorState?.changedFiles ?? [],
+    commands: priorState?.commands ?? [],
+    proofArtifacts: priorState?.proofArtifacts ?? [],
+    untested: priorState?.untested ?? [],
+    resumeConflicts: priorState?.resumeConflicts ?? [],
     provenance,
     evidence: {
       workLedger: { file: ledger.file, present: ledger.present, open: ledger.open.length, done: ledger.done.length },
@@ -236,7 +261,7 @@ export function buildProjectProgression({
     source: projectProgression.sourceIdentity,
   });
   const priorMeaning = heads.length === 1 ? digestCanonical({
-    state: { ...priorState, activeStep: null, evidence: null },
+    state: { ...carriedState, activeStep: null, evidence: null },
     source: heads[0].sourceIdentity,
   }) : null;
 

package/plugin/scripts/project-progression-session-start.mjs

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { withProgressionReader } from './project-progression-reader.mjs';
+import { drainCaptureQueue, queuedWork } from './session-snapshot-hook.mjs';
+import { replayTurnQueue } from './turn-outcome-capture.mjs';
 import { STAGE_BUDGETS_MS } from './session-start-budget.mjs';
 
 const PROGRESSION_NAMESPACE = 'project-progression';
@@ -219,20 +222,57 @@ export function restoreProgressionForSession({
     };
     const makeStore = storeFactory ?? ((options) => new ProjectProgressionStore({
       ...options,
+      env,
       runner: boundedRunner,
     }));
     store = makeStore({
       projectDir,
       requestedStorePath: resolution.canonicalAgentDbPath,
     });
+    const home = env.HOME || env.USERPROFILE || os.homedir();
+    const turns = replayTurnQueue({ projectDir, env, home, synchronous: true, runner: boundedRunner, deadlineMs: deadlineAt });
+    if (turns.pending > 0 || turns.failed > 0) {
+      const failed = miss('outbox-replay');
+      return { ...failed, pendingTurns: turns.pending,
+        context: `${failed.context} Durable turn recording remains pending; no older checkpoint was injected.` };
+    }
+    const suspended = ['persisted turn capture opt-out', 'turn capture policy unreadable or invalid'].includes(turns.skipped);
+    if (turns.skipped && !suspended && !['RUVNET_TURN_CAPTURE=off',
+      'no project memory db; persisted opt-in required'].includes(turns.skipped)) return miss('outbox-replay');
+    if (suspended && initializing) return {
+      status: 'unavailable', reason: 'capture-suspended', severity: 'info',
+      context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nCapture consent suspends replay; no canonical store was created.',
+    };
+    if (suspended && (store.pendingReplayCount?.() > 0 || queuedWork(resolution.projectRoot) > 0)) {
+      const failed = miss('outbox-replay');
+      return { ...failed, context: `${failed.context} Replay is suspended by capture consent; no older checkpoint was injected.` };
+    }
     if (initializing) {
       fs.mkdirSync(path.dirname(resolution.canonicalAgentDbPath), { recursive: true, mode: 0o700 });
       initializeCanonicalStore(store, resolution);
     }
-    // COMMITTED ROWS ONLY (ADR-073 §5). Replay is a write, a write is a `ruflo memory store`
-    // process, and one of those costs more than this entire boundary's budget. Pending durable
-    // snapshots are REPORTED below and replayed at the next capture boundary or by /checkpoint.
-    const restored = store.restoreLatest({ maxOutputBytes: payloadLimit, replayPending: false, projectToBound: true });
+    if (!suspended) {
+      const queue = drainCaptureQueue({ projectDir, budgetMs: Math.max(0, deadlineAt - Date.now()),
+        makeStoreFactory: () => () => store });
+      if (queue.state !== 'settled') {
+        const failed = miss('outbox-replay');
+        return { ...failed, pendingReplay: queue.pending,
+          context: `${failed.context} Durable capture work remains pending; no older checkpoint was injected.` };
+      }
+    }
+    // A pending snapshot is newer observable work. Never label an older committed head restored
+    // while that work remains unverified. Replay uses the same managed exact-readback store path.
+    let restored;
+    try {
+      restored = store.restoreLatest({ maxOutputBytes: payloadLimit, replayPending: !suspended, projectToBound: true });
+    } catch (error) {
+      if (store.pendingReplayCount?.() > 0) {
+        const failed = miss('outbox-replay');
+        return { ...failed, pendingReplay: store.pendingReplayCount(),
+          context: `${failed.context} ${store.pendingReplayCount()} durable snapshot(s) remain pending; no older checkpoint was injected.` };
+      }
+      throw error;
+    }
     if (!validResume(restored)) return miss('malformed-store');
     const summaryNotice = restored.projected
       ? '\n[BOUNDED CONTINUITY SUMMARY] The merged current goal and next action are preserved exactly; '

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

@@ -9,6 +9,7 @@ import {
   restoreProjectProgression,
   validateProgressionSnapshot,
 } from './project-progression-contract.mjs';
+import { resolveTurnDb } from './turn-outcome-capture.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { withProgressionReader } from './project-progression-reader.mjs';
 import { resolveRuflo, rufloInvocation, RUFLO_MISSING } from './ruflo-bin.mjs';
@@ -323,6 +324,8 @@ export class ProjectProgressionStore {
   constructor({
     projectDir,
     requestedStorePath,
+    env = process.env,
+    brainHome = env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain'),
     rufloBinary = resolveRuflo(),
     runner = defaultRunner,
     clock = () => new Date().toISOString(),
@@ -336,6 +339,7 @@ export class ProjectProgressionStore {
     // 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.brainHome = brainHome;
     this.rufloBinary = rufloBinary;
     this.runner = runner;
     this.clock = clock;
@@ -374,8 +378,17 @@ export class ProjectProgressionStore {
     if (!verdict.ok) throw new Error(`invalid progression snapshot: ${verdict.errors.join(', ')}`);
   }
 
+  requireCaptureConsent(snapshot) {
+    const capturePath = snapshot.sourceIdentity.capturePath;
+    const target = resolveTurnDb({ projectDir: capturePath ?? snapshot.sourceIdentity.checkoutPath,
+      brainHome: this.brainHome, requestedStorePath: this.resolution.canonicalAgentDbPath,
+      unknownOriginalPath: !capturePath });
+    if (target.skipped) throw new Error(`progression capture suspended: ${target.skipped}`);
+  }
+
   appendExact(snapshot, { onPhase = () => {} } = {}) {
     this.validateSnapshot(snapshot);
+    this.requireCaptureConsent(snapshot);
     const stored = this.run([
       'memory', 'store', '--key', snapshot.eventKey, '--value', JSON.stringify(snapshot),
       '--namespace', PROGRESSION_NAMESPACE, '--no-upsert', '--provenance', 'system_observation',
@@ -429,6 +442,7 @@ export class ProjectProgressionStore {
 
   capture(snapshot, { onPhase = () => {} } = {}) {
     this.validateSnapshot(snapshot);
+    this.requireCaptureConsent(snapshot);
     this.outbox.appendSnapshot(snapshot);
     onPhase('outbox-fsynced');
     const receipt = this.appendExact(snapshot, { onPhase });