ruvnet-brain 4.5.5 → 4.5.7

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

@@ -2,6 +2,66 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const OUTBOX_NAME = 'project-progression-outbox.jsonl';
+const READ_CHUNK_BYTES = 64 * 1024;
+
+// Decode only complete records, so a multibyte character crossing reads stays intact.
+function* readJsonl(file) {
+  let fd;
+  try { fd = fs.openSync(file, 'r'); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+  let parts = [];
+  let line = 0;
+  const parse = (bytes, terminated) => {
+    if (!bytes.length) return undefined;
+    const text = bytes.toString('utf8');
+    if (!text.trim()) return undefined;
+    try { return JSON.parse(text); } catch {
+      if (!terminated) return undefined;
+      throw new Error(`malformed outbox record at line ${line}`);
+    }
+  };
+  try {
+    let length;
+    while ((length = fs.readSync(fd, chunk, 0, chunk.length, null))) {
+      let start = 0;
+      for (let end = 0; end < length; end += 1) {
+        if (chunk[end] !== 10) continue;
+        parts.push(Buffer.from(chunk.subarray(start, end)));
+        line += 1;
+        const record = parse(Buffer.concat(parts), true);
+        if (record !== undefined) yield record;
+        parts = []; start = end + 1;
+      }
+      if (start < length) parts.push(Buffer.from(chunk.subarray(start, length)));
+    }
+    if (parts.length) {
+      line += 1;
+      const record = parse(Buffer.concat(parts), false);
+      if (record !== undefined) yield record;
+    }
+  } finally { fs.closeSync(fd); }
+}
+
+// Inspect only the final record; preceding history is never decoded or copied.
+function finalRecord(fd, size) {
+  const parts = [];
+  let position = size;
+  while (position > 0) {
+    const length = Math.min(READ_CHUNK_BYTES, position);
+    position -= length;
+    const chunk = Buffer.alloc(length);
+    let read = 0;
+    while (read < length) {
+      const count = fs.readSync(fd, chunk, read, length - read, position + read);
+      if (!count) throw new Error('outbox tail changed during inspection');
+      read += count;
+    }
+    const delimiter = chunk.lastIndexOf(10);
+    parts.unshift(delimiter < 0 ? chunk : chunk.subarray(delimiter + 1));
+    if (delimiter >= 0) break;
+  }
+  return Buffer.concat(parts).toString('utf8');
+}
 
 function requireIdentity(value, label) {
   if (typeof value !== 'string' || !value) throw new TypeError(`${label} must be a non-empty string`);
@@ -31,8 +91,7 @@ export class ProgressionOutbox {
         const last = Buffer.alloc(1);
         fs.readSync(fd, last, 0, 1, size - 1);
         if (last[0] !== 10) {
-          const content = fs.readFileSync(fd, 'utf8');
-          try { JSON.parse(content.slice(content.lastIndexOf('\n') + 1)); }
+          try { JSON.parse(finalRecord(fd, size)); }
           catch { throw new Error('incomplete outbox final record; preserve and recover the torn tail before appending'); }
           separator = '\n';
         }
@@ -66,18 +125,23 @@ export class ProgressionOutbox {
     return this.appendRecord({ type: 'commit', ...receipt });
   }
 
-  records() {
-    if (!fs.existsSync(this.path)) return [];
-    const content = fs.readFileSync(this.path, 'utf8');
-    const lines = content.split('\n');
-    if (lines.at(-1) === '') lines.pop();
-    else {
-      // A missing delimiter is not a missing record; only a crash-torn JSON suffix is incomplete.
-      try { JSON.parse(lines.at(-1)); } catch { lines.pop(); }
+  /** Disposition of one frozen payload, never a commit for its conflicting original key. */
+  markRecovered(snapshot, receipt) {
+    for (const [label, value] of Object.entries({ eventKey: snapshot?.eventKey,
+      payloadDigest: snapshot?.payloadDigest, recoveryEventKey: receipt?.eventKey,
+      recoveryPayloadDigest: receipt?.payloadDigest, readbackDigest: receipt?.readbackDigest,
+      committedAt: receipt?.committedAt })) requireIdentity(value, label);
+    if (receipt.eventKey === snapshot.eventKey || receipt.readbackDigest !== receipt.payloadDigest) {
+      throw new Error('unverified recovery disposition');
     }
-    return lines.filter(Boolean).map((line, index) => {
-      try { return JSON.parse(line); } catch { throw new Error(`malformed outbox record at line ${index + 1}`); }
-    });
+    return this.appendRecord({ type: 'recovery', eventKey: snapshot.eventKey,
+      payloadDigest: snapshot.payloadDigest, recoveryEventKey: receipt.eventKey,
+      recoveryPayloadDigest: receipt.payloadDigest, readbackDigest: receipt.readbackDigest,
+      committedAt: receipt.committedAt });
+  }
+
+  records() {
+    return [...readJsonl(this.path)];
   }
 
   /**
@@ -92,17 +156,33 @@ export class ProgressionOutbox {
     const snapshots = new Map();
     const committed = new Map();
     const quarantined = new Map();
-    for (const record of this.records()) {
+    const recoveries = [];
+    let ordinal = 0;
+    for (const record of readJsonl(this.path)) {
+      ordinal += 1;
       requireIdentity(record?.eventKey, 'outbox eventKey');
       requireIdentity(record?.payloadDigest, 'outbox payloadDigest');
       if (record.type === 'snapshot') {
         const prior = snapshots.get(record.eventKey);
         if (prior && prior.payloadDigest !== record.payloadDigest) quarantined.set(record.eventKey, 'outbox event key collision');
-        else snapshots.set(record.eventKey, record);
+        // Retain identity/recovery metadata, never every historical snapshot's full payload.
+        // A second incremental scan materializes only the unresolved payloads selected here.
+        else snapshots.set(record.eventKey, { eventKey: record.eventKey, payloadDigest: record.payloadDigest,
+          ordinal, recoveryDiagnostics: record.snapshot?.recoveryDiagnostics && {
+            originalEventKey: record.snapshot.recoveryDiagnostics.originalEventKey,
+            frozenPayloadDigest: record.snapshot.recoveryDiagnostics.frozenPayloadDigest,
+          }, snapshotDigest: record.snapshot?.payloadDigest });
       } else if (record.type === 'commit') {
         const prior = committed.get(record.eventKey);
         if (prior && prior !== record.payloadDigest) quarantined.set(record.eventKey, 'outbox commit collision');
         committed.set(record.eventKey, record.payloadDigest);
+      } else if (record.type === 'recovery') {
+        requireIdentity(record.recoveryEventKey, 'recovery event key');
+        requireIdentity(record.recoveryPayloadDigest, 'recovery payload digest');
+        if (record.eventKey === record.recoveryEventKey || record.readbackDigest !== record.recoveryPayloadDigest) {
+          throw new Error('unverified recovery disposition');
+        }
+        recoveries.push(record);
       } else {
         throw new Error('unsupported outbox record');
       }
@@ -113,11 +193,28 @@ export class ProgressionOutbox {
         quarantined.set(record.eventKey, 'outbox commit digest mismatch');
       }
     }
+    const recovered = new Set(recoveries.filter((record) => {
+      const target = snapshots.get(record.recoveryEventKey);
+      return !quarantined.has(record.recoveryEventKey)
+        && committed.get(record.recoveryEventKey) === record.recoveryPayloadDigest
+        && target?.snapshotDigest === record.recoveryPayloadDigest
+        && target.recoveryDiagnostics?.originalEventKey === record.eventKey
+        && target.recoveryDiagnostics?.frozenPayloadDigest === record.payloadDigest;
+    }).map((record) => `${record.eventKey}:${record.payloadDigest}`));
     this.quarantine = [...quarantined].map(([eventKey, reason]) => ({ eventKey, reason }));
-    return [...snapshots.values()]
-      .filter((record) => !quarantined.has(record.eventKey) && !committed.has(record.eventKey))
-      .sort((left, right) => left.eventKey.localeCompare(right.eventKey))
-      .map((record) => record.snapshot);
+    const pending = new Map([...snapshots.values()]
+      .filter((record) => !quarantined.has(record.eventKey) && !committed.has(record.eventKey)
+        && !recovered.has(`${record.eventKey}:${record.payloadDigest}`))
+      .map((record) => [record.ordinal, record.eventKey]));
+    const payloads = [];
+    ordinal = 0;
+    if (pending.size) {
+      for (const record of readJsonl(this.path)) {
+        ordinal += 1;
+        if (pending.has(ordinal)) payloads.push({ eventKey: pending.get(ordinal), snapshot: record.snapshot });
+      }
+    }
+    return payloads.sort((left, right) => left.eventKey.localeCompare(right.eventKey)).map((record) => record.snapshot);
   }
 
   /** Keys pendingSnapshots() refused to replay because their records disagree, with the reason. */

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

@@ -29,6 +29,7 @@
  * within those bounds.
  */
 import crypto from 'node:crypto';
+import { enrichStateWithObservation } from './project-progression-hook.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { digestCanonical, fieldAuthorityAllows, redactProgression, restoreProjectProgression } from './project-progression-contract.mjs';
@@ -250,6 +251,16 @@ export function buildProjectProgression({
     completeProjectState,
   });
   const projectProgression = redactedProgression;
+  // Compare the same redacted observation the native writer will append, without returning it
+  // twice. Tool input and terminal evidence must participate before the no-op decision.
+  const observedState = redactProgression(enrichStateWithObservation(
+    projectProgression.completeProjectState, { ...payload, hook_event_name: trigger },
+  )).value;
+  // A committed sequence is not an event identity: several boundaries may freeze before replay.
+  // Bind all immutable captured fields (including the native observation and occurrence time).
+  projectProgression.dedupId += `:${digestCanonical({
+    ...projectProgression, completeProjectState: observedState,
+  })}`;
 
   // RETENTION (ADR-073). Three capture boundaries per session times every session is unbounded
   // growth unless a capture that changes nothing writes nothing. Compare what a snapshot MEANS —
@@ -257,7 +268,7 @@ export function buildProjectProgression({
   // differ (sequence, timestamp, dedup id, the trigger that happens to be firing, and the evidence
   // block's own timestamps), because comparing those would make every capture look novel.
   const meaning = digestCanonical({
-    state: { ...projectProgression.completeProjectState, activeStep: null, evidence: null },
+    state: { ...observedState, activeStep: null, evidence: null },
     source: projectProgression.sourceIdentity,
   });
   const priorMeaning = heads.length === 1 ? digestCanonical({

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

@@ -8,6 +8,7 @@ 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';
+import { operatorProgressionSuspension } from './project-progression-suspension.mjs';
 
 const PROGRESSION_NAMESPACE = 'project-progression';
 
@@ -191,6 +192,15 @@ export function restoreProgressionForSession({
   },
 } = {}) {
   const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
+  try {
+    if (operatorProgressionSuspension(env)) {
+      // Turn recording is independent: suspension must not strand ordinary AgentDB capture.
+      const turns = replayTurnQueue({ projectDir, env, home: env.HOME || os.homedir(), synchronous: true,
+        deadlineMs: Date.now() + deadlineMs });
+      return { status: 'unavailable', reason: 'operator-suspended', severity: 'info', pendingTurns: turns.pending,
+        context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nAutomatic progression capture, replay and restore are operator-suspended. Evidence and queues are preserved. Ordinary AgentDB memory and explicit checkpoints remain available; no project progression was restored.' };
+    }
+  } catch { return unknown('restore-failed'); }
   let resolution;
   try {
     resolution = resolveProjectStore({ projectDir });

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

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { ProgressionOutbox } from './project-progression-outbox.mjs';
 import {
+  createProgressionSnapshot,
   digestCanonical,
   restoreProjectProgression,
   validateProgressionSnapshot,
@@ -87,10 +88,26 @@ export function projectResumePayloadToBound(payload, maxOutputBytes) {
     });
   }
 
+  if (size() > maxOutputBytes && Array.isArray(summary.state?.resumeConflicts)) {
+    const groups = new Map();
+    for (const conflict of payload.state.resumeConflicts) {
+      if (!groups.has(conflict.field)) groups.set(conflict.field, []);
+      groups.get(conflict.field).push(conflict);
+    }
+    if (groups.size < payload.state.resumeConflicts.length) {
+      summary.state.resumeConflicts = [...groups].map(([field, conflicts]) => ({
+        field, conflictCount: conflicts.length,
+        valueCount: conflicts.reduce((count, conflict) => count + (conflict.values ?? []).length, 0),
+        conflictsDigest: digestCanonical(conflicts),
+      }));
+      omissions.push({ path: 'state.resumeConflicts', ...omissionSummary(payload.state.resumeConflicts) });
+    }
+  }
+
   if (size() > maxOutputBytes) recordOmission(summary.state, 'journalHeads', 'state.journalHeads');
   // Least central detail first. currentGoal and nextAction are deliberately absent from this list.
   const stateFields = [
-    'commands', 'proofArtifacts', 'changedFiles', 'completed', 'untested', 'decisions',
+    'observations', 'commands', 'proofArtifacts', 'changedFiles', 'completed', 'untested', 'decisions',
     'plan', 'inProgress', 'blockers', 'failures', 'acceptanceContract', 'provenance',
     'evidence', 'activeStep', 'activeProcess', 'sourceIdentity',
   ];
@@ -450,6 +467,41 @@ export class ProjectProgressionStore {
     return receipt;
   }
 
+  /** Frozen queue recovery never rewrites the conflicting row or marks its key committed. */
+  captureFrozen(snapshot, { canCommit } = {}) {
+    if (typeof canCommit !== 'function') throw new Error('frozen recovery requires replay fencing');
+    const fenced = () => { if (!canCommit()) throw new Error('progression recovery lost replay fencing'); };
+    fenced();
+    try { return { snapshot, receipt: this.capture(snapshot, { onPhase: fenced }) }; } catch (error) {
+      if (error.message !== 'progression readback digest mismatch') throw error;
+    }
+    // An independently retrieved exact canonical value must be valid for this project. A failed,
+    // absent, malformed or foreign read is never evidence that the immutable key collided.
+    const exact = this.retrieveSnapshots([snapshot.eventKey]);
+    if (exact.rejected.length || exact.snapshots.length !== 1) throw new Error('immutable collision is not verified');
+    const existing = exact.snapshots[0];
+    this.validateSnapshot(existing);
+    if (existing.eventKey !== snapshot.eventKey || existing.payloadDigest === snapshot.payloadDigest) {
+      throw new Error('immutable collision is not verified');
+    }
+    const identity = { originalEventKey: snapshot.eventKey,
+      frozenPayloadDigest: snapshot.payloadDigest, existingPayloadDigest: existing.payloadDigest };
+    const created = createProgressionSnapshot({ ...snapshot,
+      dedupId: `immutable-recovery:${digestCanonical(identity)}` });
+    // Preserve the frozen state and source exactly; diagnostics carry no instruction authority.
+    const { payloadDigest: _digest, ...body } = created;
+    body.redactions = snapshot.redactions;
+    body.recoveryDiagnostics = { kind: 'immutable-event-key-collision', authoritative: false, ...identity };
+    const recovered = Object.freeze({ ...body, payloadDigest: digestCanonical(body) });
+    this.validateSnapshot(recovered);
+    this.requireCaptureConsent(recovered);
+    fenced();
+    const receipt = this.capture(recovered, { onPhase: fenced });
+    fenced();
+    this.outbox.markRecovered(snapshot, receipt);
+    return { snapshot: recovered, receipt };
+  }
+
   replay() {
     const receipts = [];
     for (const snapshot of this.outbox.pendingSnapshots()) {

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

@@ -0,0 +1,60 @@
+// Operator containment only (#390 B). No store, checkpoint, event, turn or search is disabled here.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+const suspendedResults = new WeakSet();
+export function progressionSuspensionFile(env = process.env) {
+  return path.join(env.RUVNET_BRAIN_STATE_DIR || path.join(env.HOME || os.homedir(), '.config', 'ruvnet-brain'), 'brain-progression-suspension');
+}
+export function operatorProgressionSuspension(env = process.env) {
+  if (env.RUVNET_BRAIN_PROGRESSION_SUSPENDED === '1') return { source: 'environment' };
+  if (env.RUVNET_BRAIN_PROGRESSION_SUSPENDED && env.RUVNET_BRAIN_PROGRESSION_SUSPENDED !== '0') {
+    throw new Error('invalid automatic progression suspension environment setting');
+  }
+  let value;
+  try { value = JSON.parse(fs.readFileSync(progressionSuspensionFile(env), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw new Error('automatic progression suspension policy unreadable or invalid'); }
+  if (value?.schemaVersion !== 1 || typeof value.suspended !== 'boolean') {
+    throw new Error('automatic progression suspension policy unreadable or invalid');
+  }
+  return value.suspended ? { source: 'operator-state' } : null;
+}
+export function automaticProgressionSuspensionResult(env = process.env, fields = {}) {
+  const control = operatorProgressionSuspension(env);
+  if (!control) return null;
+  const result = Object.freeze({ ...fields, progressionSuspended: true, progressionCaptured: false,
+    receipt: null, skipped: 'operator suspended automatic project progression', suspensionSource: control.source });
+  suspendedResults.add(result);
+  return result;
+}
+// A look-alike public flag is never authority to bypass an unexpected capture failure.
+export const isAutomaticProgressionSuspension = (result) => Boolean(result && suspendedResults.has(result));
+
+/** Explicit operator configuration: replacing this control file never touches evidence or queues. */
+export function setOperatorProgressionSuspension(suspended, { env = process.env } = {}) {
+  if (typeof suspended !== 'boolean') throw new TypeError('suspended must be a boolean');
+  const file = progressionSuspensionFile(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, suspended }), { flag: 'wx', mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally { try { fs.unlinkSync(temporary); } catch { /* renamed or not created */ } }
+  return operatorProgressionSuspension(env);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const argv = process.argv.slice(2);
+    if (argv.length !== 1 || !['--suspend', '--resume', '--status'].includes(argv[0])) {
+      throw new Error('usage: project-progression-suspension.mjs --suspend | --resume | --status');
+    }
+    if (argv[0] !== '--status') setOperatorProgressionSuspension(argv[0] === '--suspend');
+    const control = operatorProgressionSuspension();
+    console.log(JSON.stringify({ automaticProgression: control ? 'operator-suspended' : 'enabled', source: control?.source || null,
+      evidencePreserved: true, explicitCheckpointsAvailable: true }));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

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

@@ -5,9 +5,11 @@ import crypto from 'node:crypto';
 import os from 'node:os';
 import { developmentHooksSuspended } from './development-maintenance.mjs';
 import { resolveTurnDb } from './turn-outcome-capture.mjs';
+import { automaticProgressionSuspensionResult } from './project-progression-suspension.mjs';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { redactText } from './continuity-events.mjs';
+import { conditionNotice } from './continuity-journal.mjs';
 import { normalizeHostEvent } from './hook-input.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { withProgressionReader } from './project-progression-reader.mjs';
@@ -75,20 +77,25 @@ export function normalizeTransition(payload, event, { now = () => new Date().toI
   const toolInput = input.tool_input ?? {};
   const response = input.tool_response && typeof input.tool_response === 'object' ? input.tool_response : {};
   const exitCode = [response.exit_code, response.exitCode, response.status].find(Number.isSafeInteger);
-  const failure = event === 'PostToolUseFailure' || response.isError === true || input.is_error === true || (Number.isSafeInteger(exitCode) && exitCode !== 0);
-  const interrupted = response.interrupted === true || response.signal === 'SIGINT';
+  const error = typeof response.error === 'string' && response.error ? redactText(response.error).slice(0, 4096) : undefined;
+  const signal = typeof response.signal === 'string' && response.signal ? redactText(response.signal).slice(0, 100) : undefined;
+  const failure = Boolean(error) || event === 'PostToolUseFailure' || response.isError === true || input.is_error === true || (Number.isSafeInteger(exitCode) && exitCode !== 0);
+  const interrupted = response.interrupted === true || Boolean(signal);
+  const declaredOutcome = ['success', 'failure', 'interrupted', 'unknown'].includes(response.outcome) ? response.outcome : null;
   // Measured native Claude Bash PostToolUse has no exit code. Its completion envelope
   // is host-reported success, never an inferred exit-code zero. Other hosts stay unknown.
   const claudeBashCompletion = host === 'claude' && input.tool_name === 'Bash' && event === 'PostToolUse'
     && typeof response.stdout === 'string' && typeof response.stderr === 'string'
     && response.interrupted === false && typeof response.isImage === 'boolean'
     && typeof response.noOutputExpected === 'boolean';
-  const outcome = event === 'PreToolUse' ? 'pending' : interrupted ? 'interrupted' : failure ? 'failure'
-    : Number.isSafeInteger(exitCode) || response.success === true || response.ok === true || claudeBashCompletion ? 'success' : 'unknown';
+  const outcome = event === 'PreToolUse' ? 'pending' : error ? 'failure' : interrupted ? 'interrupted' : failure ? 'failure'
+    : declaredOutcome || (Number.isSafeInteger(exitCode) || response.success === true || response.ok === true || claudeBashCompletion ? 'success' : 'unknown');
   return { ...common, kind: 'tool-observation', tool: String(input.tool_name).split('__').at(-1).slice(0, 100),
     intent: semanticIntent(toolInput.description ?? toolInput.command ?? toolInput.cmd ?? toolInput.file_path), outcome,
     ...(outcome === 'success' && claudeBashCompletion ? { outcomeEvidence: 'claude-bash-completion' } : {}),
-    ...(event !== 'PreToolUse' && Number.isSafeInteger(exitCode) ? { exitCode } : {}) };
+    ...(event !== 'PreToolUse' && Number.isSafeInteger(exitCode) ? { exitCode } : event !== 'PreToolUse' && (response.exit_code === null || response.exitCode === null) ? { exitCode: null } : {}),
+    ...(event !== 'PreToolUse' && error ? { error } : {}),
+    ...(event !== 'PreToolUse' && signal ? { signal } : {}) };
 }
 
 export function readTransitionHistory(resolution, { deadlineAt = Infinity } = {}) {
@@ -107,6 +114,11 @@ export function readTransitionHistory(resolution, { deadlineAt = Infinity } = {}
 export function buildTransitionProgression({ resolution, observation, snapshots = [], sessionIdentity, host, sourceIdentity: originalSourceIdentity }) {
   const restored = restoreProjectProgression(snapshots, { expectedProjectIdentity: resolution.projectIdentity });
   if (snapshots.length && !restored.ok) throw new Error('nonempty transition journal has no coherent ancestry');
+  return buildRestoredTransitionProgression({ resolution, observation, snapshots, sessionIdentity, host, sourceIdentity: originalSourceIdentity }, restored);
+}
+
+// Only the validated result computed in this module can reach this private builder.
+function buildRestoredTransitionProgression({ resolution, observation, snapshots, sessionIdentity, host, sourceIdentity: originalSourceIdentity }, restored) {
   const heads = snapshots.filter((snapshot) => restored.heads.includes(snapshot.eventKey));
   const prior = restored.state;
   const empty = Object.fromEntries(['plan', 'completed', 'inProgress', 'blockers', 'failures', 'decisions', 'changedFiles', 'commands', 'proofArtifacts', 'untested', 'resumeConflicts'].map((key) => [key, []]));
@@ -138,14 +150,17 @@ export function observeTransitionSource(resolution, projectDir = resolution.chec
 
 /** Called only by the fenced queue drainer; current heads merge, original observations stay fixed. */
 export function captureNormalizedTransition(job, { readHistory = readTransitionHistory, capture = runSessionSnapshotHook,
-  budgetMs = 6500, makeStoreFactory, now = Date.now } = {}) {
+  budgetMs = 6500, makeStoreFactory, now = Date.now, env = process.env } = {}) {
+  const suspended = automaticProgressionSuspensionResult(env);
+  if (suspended) return suspended;
   const deadlineAt = now() + budgetMs;
   const resolution = resolveProjectStore({ projectDir: job.originProjectDir, gitTimeoutMs: Math.max(1, Math.min(500, budgetMs)) });
   const normalized = job.payload.normalizedTransition;
   if (!normalized || normalized.observation?.authoritative !== false || !normalized.observation?.id
     || normalized.sourceIdentity?.checkoutPath !== resolution.checkoutRoot) throw new Error('invalid normalized transition binding');
   const snapshots = readHistory(resolution, { deadlineAt });
-  if (snapshots.length && !restoreProjectProgression(snapshots, { expectedProjectIdentity: resolution.projectIdentity }).ok) {
+  const restored = restoreProjectProgression(snapshots, { expectedProjectIdentity: resolution.projectIdentity });
+  if (snapshots.length && !restored.ok) {
     throw new Error('nonempty transition journal has no coherent ancestry');
   }
   // A failed first store already fsynced a snapshot to the outbox. If startup/replay committed
@@ -159,10 +174,10 @@ export function captureNormalizedTransition(job, { readHistory = readTransitionH
   if (committed) return { progressionCaptured: true, eventId: normalized.observation.id,
     receipt: { eventKey: committed.eventKey, payloadDigest: committed.payloadDigest,
       readbackDigest: committed.payloadDigest, readPath: 'canonical progression reader' } };
-  const progression = buildTransitionProgression({ resolution, observation: normalized.observation,
+  const progression = buildRestoredTransitionProgression({ resolution, observation: normalized.observation,
     snapshots, sessionIdentity: job.payload.session_id, host: job.host,
-    sourceIdentity: normalized.sourceIdentity });
-  const result = capture(job.originProjectDir, job.event, { host: job.host, budgetMs: Math.max(0, deadlineAt - now()),
+    sourceIdentity: normalized.sourceIdentity }, restored);
+  const result = capture(job.originProjectDir, job.event, { host: job.host, env, budgetMs: Math.max(0, deadlineAt - now()),
     ...(makeStoreFactory ? { makeStoreFactory } : {}), writeMetadata: false,
     rawInput: JSON.stringify({ session_id: job.payload.session_id, hook_event_name: job.event, projectProgression: progression }),
     captureTurn: () => ({ recorded: false, skipped: 'transition boundary' }),
@@ -173,6 +188,8 @@ export function captureNormalizedTransition(job, { readHistory = readTransitionH
 export function runProjectTransitionHook(projectDir, event, { payload = {}, host = process.env.RUVNET_HOOK_HOST || 'claude',
   readHistory = readTransitionHistory, capture = runSessionSnapshotHook, env = process.env } = {}) {
   if (developmentHooksSuspended(projectDir)) return { state: 'skipped', reason: 'development hooks suspended' };
+  const suspended = automaticProgressionSuspensionResult(env, { state: 'suspended', reason: 'automatic project progression is operator-suspended' });
+  if (suspended) return suspended;
   const observation = normalizeTransition(payload, event, { host });
   if (observation.skipped) return { state: 'skipped', reason: observation.skipped };
   const brainHome = env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
@@ -183,22 +200,33 @@ export function runProjectTransitionHook(projectDir, event, { payload = {}, host
   const transportEvent = event === 'PostToolUseFailure' ? 'PostToolUse' : event;
   // Fsync the selected observation BEFORE any history enumeration/merge. A deadline, corruption,
   // or long-lived project must leave it pending rather than erase it or fabricate root ancestry.
-  const queued = queueCapture({ projectDir: resolution.projectRoot, originProjectDir: projectDir, event: transportEvent, host,
+  const queued = queueCapture({ projectDir: resolution.projectRoot, originProjectDir: projectDir, env, event: transportEvent, host,
     payload: { session_id: payload.session_id, hook_event_name: transportEvent,
       normalizedTransition: { observation, sourceIdentity: observeTransitionSource(resolution, projectDir) } } });
   if (!queued) return { state: 'degraded', reason: 'normalized observation queue unwritable', eventId: observation.id };
   let result = null;
-  runOutboxReplay({ projectDir: resolution.projectRoot, budgetMs: Math.min(6500, effectiveBudgetMs(env)),
-    captureNormalized: (job, options) => captureNormalizedTransition(job, { ...options, readHistory, capture }),
+  runOutboxReplay({ projectDir: resolution.projectRoot, env, budgetMs: Math.min(6500, effectiveBudgetMs(env)),
+    captureNormalized: (job, options) => captureNormalizedTransition(job, { ...options, env, readHistory, capture }),
     onCaptured: (captured) => { if (captured?.eventId === observation.id) result = captured; } });
-  if (!result?.receipt) replayOutboxDetached({ projectDir: resolution.projectRoot });
+  if (!result?.receipt) replayOutboxDetached({ projectDir: resolution.projectRoot, env });
   return { state: result?.progressionCaptured && result.receipt ? 'committed' : 'pending', eventId: observation.id, result };
 }
 
+/** One pending-readback condition across prompt/tool boundaries and both CLI entrypoints. */
+export function transitionPendingNotice(projectDir, payload, message) {
+  const { projectRoot } = resolveProjectStore({ projectDir, gitTimeoutMs: 500 });
+  return conditionNotice({ swarm: path.join(projectRoot, '.swarm'),
+    session: normalizeHostEvent(payload)?.session_id, condition: 'project-transition-pending-readback', message });
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     const payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
-    const result = runProjectTransitionHook(payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd(), process.argv[2], { payload });
-    if (result.state === 'pending') process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: process.argv[2], additionalContext: 'Project memory transition is pending; exact AgentDB readback was not verified at this boundary.' } }));
+    const projectDir = payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const result = runProjectTransitionHook(projectDir, process.argv[2], { payload });
+    if (result.state === 'pending') {
+      const message = transitionPendingNotice(projectDir, payload, 'Project memory transition is pending; exact AgentDB readback was not verified at this boundary.');
+      if (message) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: process.argv[2], additionalContext: message } }));
+    }
   } catch { process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition capture degraded; exact readback was not verified.' })); }
 }

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

@@ -17,6 +17,7 @@ import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { resolveTurnDb, captureTurnOutcome } from './turn-outcome-capture.mjs';
 import { captureContinuityEvents, stopNotice } from './continuity-journal.mjs';
+import { automaticProgressionSuspensionResult } from './project-progression-suspension.mjs';
 
 /**
  * The capture boundary's whole budget. hooks.json declares 10s; this keeps the internal work well
@@ -158,12 +159,15 @@ export function runSessionSnapshotHook(projectDir, event, {
     continuity = { recorded: 0, skipped: `continuity capture failed: ${error.message}` };
   }
   const idle = { metadataWritten, progressionCaptured: false, receipt: null, turn, continuity };
+  const operatorSuspended = automaticProgressionSuspensionResult(env, idle);
+  if (operatorSuspended) return operatorSuspended;
 
   if (hasProjectProgression(payload)) {
     if (payload.hook_event_name !== event) {
       throw new Error(`progression boundary mismatch: expected ${event}, received ${payload.hook_event_name}`);
     }
-    const result = captureProgression({ host, payload, projectDir, storeFactory: (options) => makeStoreFactory(now() + budgetMs)({ ...options, env }) });
+    const result = captureProgression({ host, payload, projectDir, recoverFrozen: Boolean(ordered),
+      canCommit: () => Boolean(ordered) && refreshReplayLock(resolveProjectStore({ projectDir }).projectRoot, ordered), storeFactory: (options) => makeStoreFactory(now() + budgetMs)({ ...options, env }) });
     return { ...idle, progressionCaptured: true, receipt: result.receipt };
   }
 
@@ -205,7 +209,7 @@ export function runSessionSnapshotHook(projectDir, event, {
     try { frozen = produce({ resolution, projectDir, payload, host, trigger: event }); } catch { frozen = null; }
     const queued = frozen?.projectProgression ? queueCapture({ projectDir: root, originProjectDir: projectDir, env, event, host,
       payload: { session_id: payload.session_id, hook_event_name: event, projectProgression: frozen.projectProgression } }) : null;
-    const handed = queued ? spawnReplay({ projectDir: root, token }) : false;
+    const handed = queued ? spawnReplay({ projectDir: root, token, env }) : 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)'}`
@@ -261,7 +265,7 @@ export function runSessionSnapshotHook(projectDir, event, {
       // 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 });
+      handedLock = !ordered && budgetMs < REPLAY_MIN_BUDGET_MS && pendingCount() > 0 && spawnReplay({ projectDir: root, token, env });
       return { ...idle, replayed, skipped: `capture deferred: ${error.message}`,
         ...(handedLock ? { replaySkipped: 'deferred capture handed to a detached worker' } : {}) };
     }
@@ -280,9 +284,9 @@ export function runSessionSnapshotHook(projectDir, event, {
     // 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 }))) {
+      if (!(queuedWork(root) && spawnReplay({ projectDir: root, token, env }))) {
         releaseReplayLock(root, token);
-        if (queuedWork(root)) spawnReplay({ projectDir: root });
+        if (queuedWork(root)) spawnReplay({ projectDir: root, env });
       }
     }
   }
@@ -296,10 +300,14 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-
   // Finish evaluating this module before importing its transition consumer.
   void (async () => {
   try {
-    const { runProjectTransitionHook } = await import('./project-transition-hook.mjs');
+    const { runProjectTransitionHook, transitionPendingNotice } = await import('./project-transition-hook.mjs');
     const payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
-    const result = runProjectTransitionHook(payload.cwd || projectDirectory(), process.argv[2], { payload });
-    if (result.state === 'pending') process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition remains pending; exact readback was not verified.' }));
+    const projectDir = payload.cwd || projectDirectory();
+    const result = runProjectTransitionHook(projectDir, process.argv[2], { payload });
+    if (result.state === 'pending') {
+      const message = transitionPendingNotice(projectDir, payload, 'Project memory transition remains pending; exact readback was not verified.');
+      if (message) process.stdout.write(JSON.stringify({ systemMessage: message }));
+    }
   } catch { process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition capture degraded; exact readback was not verified.' })); }
   })();
 } else if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {

package/plugin/scripts/turn-outcome-capture.mjs

@@ -110,10 +110,12 @@ export function claudeTurn(lines) {
 }
 
 function readTail(file, bytes = TRANSCRIPT_TAIL_BYTES) {
-  const size = fs.statSync(file).size;
-  const offset = Math.max(0, size - bytes);
   const handle = fs.openSync(file, 'r');
   try {
+    const stat = fs.fstatSync(handle);
+    if (!stat.isFile()) throw new Error('Transcript must be a regular file');
+    const size = stat.size;
+    const offset = Math.max(0, size - bytes);
     const buf = Buffer.alloc(size - offset);
     fs.readSync(handle, buf, 0, buf.length, offset);
     const lines = buf.toString('utf8').split(/\r?\n/);
@@ -128,7 +130,9 @@ export function readSettledTranscript(file, { stableMs = 400, maxMs = 2000, slee
   const deadline = Date.now() + Math.max(0, maxMs);
   let size = -1;
   for (;;) {
-    const now = fs.statSync(file).size;
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error('Transcript must be a regular file');
+    const now = stat.size;
     if (now === size || Date.now() >= deadline) break;
     size = now;
     pause(Math.min(stableMs, Math.max(0, deadline - Date.now())));