ruvnet-brain 4.3.21 → 4.3.26

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

@@ -7,6 +7,7 @@ import {
   validateProgressionSnapshot,
 } from './project-progression-contract.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
+import { withProgressionReader } from './project-progression-reader.mjs';
 import { resolveRuflo, rufloInvocation, RUFLO_MISSING } from './ruflo-bin.mjs';
 
 const PROGRESSION_NAMESPACE = 'project-progression';
@@ -75,15 +76,29 @@ export class ProjectProgressionStore {
     runner = defaultRunner,
     clock = () => new Date().toISOString(),
     fsync,
+    // The read-only fast path (project-progression-reader.mjs). READS ONLY: `ruflo memory store`
+    // stays the sole writer of memory.db. Pass `reader: null` to force every read through the CLI.
+    reader = withProgressionReader,
   } = {}) {
     if (!rufloBinary) throw new Error(RUFLO_MISSING);
     this.resolution = resolveProjectStore({ projectDir, requestedStorePath });
     this.rufloBinary = rufloBinary;
     this.runner = runner;
     this.clock = clock;
+    this.reader = typeof reader === 'function' ? reader : null;
+    this.lastReadPath = null;
     this.outbox = new ProgressionOutbox({ projectRoot: this.resolution.projectRoot, fsync });
   }
 
+  /**
+   * Run one read through the in-process reader, or report that the CLI must serve it.
+   * Structural errors propagate unchanged — only "I cannot answer authoritatively" falls back.
+   */
+  readFast(work) {
+    if (!this.reader) return { ok: false, reason: 'reader disabled' };
+    return this.reader(this.resolution.canonicalAgentDbPath, work);
+  }
+
   run(args) {
     return this.runner(this.rufloBinary, args, {
       cwd: path.dirname(this.resolution.canonicalAgentDbPath),
@@ -110,18 +125,36 @@ export class ProjectProgressionStore {
     const alreadyStored = resultStatus(stored) !== 0;
     if (!alreadyStored) onPhase('stored');
 
-    const retrieved = this.run([
-      'memory', 'retrieve', '--key', snapshot.eventKey, '--namespace', PROGRESSION_NAMESPACE,
-      '--value-only', '--path', this.resolution.canonicalAgentDbPath,
-    ]);
-    if (resultStatus(retrieved) !== 0) {
-      const storeFailure = alreadyStored
-        ? `; store failed: ${resultText(stored, 'stderr').trim() || 'unknown error'}`
-        : '';
-      throw new Error(`progression readback failed: ${resultText(retrieved, 'stderr').trim() || 'unknown error'}${storeFailure}`);
+    // THE READ-BACK, through the fast path when it is available.
+    //
+    // This is not a shortcut past the verification — it IS the verification, taken by an independent
+    // route. Reading the row back with the same CLI process family that just wrote it proves the CLI
+    // agrees with itself; reading the bytes off disk with node:sqlite proves the row is really there.
+    // It also matters for the budget: a capture boundary gets 8s, and a cold `ruflo memory` call
+    // measured ~3s in an isolated HOME (matching the 3.0-3.4s figure from the original report), so
+    // replay + capture at two CLI calls each did not fit and left the new snapshot uncommitted in the
+    // outbox. One CLI write plus a ~1ms read fits with room to spare. The CLI remains the fallback.
+    let readbackText = null;
+    const fast = this.readFast((reader) => reader.readContent(PROGRESSION_NAMESPACE, snapshot.eventKey));
+    if (fast.ok && typeof fast.value === 'string') {
+      this.lastReadPath = 'node:sqlite';
+      readbackText = fast.value;
+    } else {
+      this.lastReadPath = `ruflo-cli (${fast.ok ? 'row absent' : fast.reason})`;
+      const retrieved = this.run([
+        'memory', 'retrieve', '--key', snapshot.eventKey, '--namespace', PROGRESSION_NAMESPACE,
+        '--value-only', '--path', this.resolution.canonicalAgentDbPath,
+      ]);
+      if (resultStatus(retrieved) !== 0) {
+        const storeFailure = alreadyStored
+          ? `; store failed: ${resultText(stored, 'stderr').trim() || 'unknown error'}`
+          : '';
+        throw new Error(`progression readback failed: ${resultText(retrieved, 'stderr').trim() || 'unknown error'}${storeFailure}`);
+      }
+      readbackText = resultText(retrieved, 'stdout');
     }
     let readback;
-    try { readback = JSON.parse(resultText(retrieved, 'stdout')); } catch { throw new Error('progression readback is not JSON'); }
+    try { readback = JSON.parse(readbackText); } catch { throw new Error('progression readback is not JSON'); }
     if (readback.payloadDigest !== snapshot.payloadDigest || digestCanonical(readback) !== digestCanonical(snapshot)) {
       throw new Error('progression readback digest mismatch');
     }
@@ -158,6 +191,16 @@ export class ProjectProgressionStore {
     requirePositiveInteger(pageSize, 'pageSize');
     requirePositiveInteger(maxEntries, 'maxEntries');
     if (pageSize > maxEntries) throw new Error('pageSize exceeds the enumeration bound');
+    const fast = this.readFast((reader) => reader.listKeys(PROGRESSION_NAMESPACE, { maxEntries }));
+    if (fast.ok) {
+      this.lastReadPath = 'node:sqlite';
+      return fast.value;
+    }
+    this.lastReadPath = `ruflo-cli (${fast.reason})`;
+    return this.listSnapshotKeysViaCli({ pageSize, maxEntries });
+  }
+
+  listSnapshotKeysViaCli({ pageSize = 100, maxEntries = 10_000 } = {}) {
     const keys = [];
     const seen = new Set();
     let offset = 0;
@@ -214,6 +257,36 @@ export class ProjectProgressionStore {
   }
 
   retrieveSnapshots(keys) {
+    // The whole batch through ONE read-only handle, or the whole batch through the CLI. Never a
+    // mixture: a half-served batch would make "exactly these rows, read exactly this way" untrue.
+    const fast = this.readFast((reader) => {
+      const snapshots = [];
+      const rejected = [];
+      for (const key of keys) {
+        const content = reader.readContent(PROGRESSION_NAMESPACE, key);
+        if (content === null) throw new Error(`progression exact retrieval failed for ${key}: row not found`);
+        let snapshot;
+        try { snapshot = JSON.parse(content); } catch {
+          rejected.push({ eventKey: key, reasons: ['readback is not JSON'] });
+          continue;
+        }
+        if (!plainRecord(snapshot) || snapshot.eventKey !== key) {
+          rejected.push({ eventKey: key, reasons: ['exact key/payload identity mismatch'] });
+          continue;
+        }
+        snapshots.push(snapshot);
+      }
+      return { snapshots, rejected: sortRejected(rejected) };
+    });
+    if (fast.ok) {
+      this.lastReadPath = 'node:sqlite';
+      return fast.value;
+    }
+    this.lastReadPath = `ruflo-cli (${fast.reason})`;
+    return this.retrieveSnapshotsViaCli(keys);
+  }
+
+  retrieveSnapshotsViaCli(keys) {
     const snapshots = [];
     const rejected = [];
     for (const key of keys) {
@@ -238,9 +311,25 @@ export class ProjectProgressionStore {
     return { snapshots, rejected: sortRejected(rejected) };
   }
 
-  restoreLatest({ pageSize = 100, maxEntries = 10_000, maxOutputBytes = 64 * 1024 } = {}) {
+  /** How many durable snapshots are fsynced but not yet committed to the canonical store. */
+  pendingReplayCount() {
+    try { return this.outbox.pendingSnapshots().length; } catch { return null; }
+  }
+
+  /**
+   * @param {{ replayPending?: boolean }} options
+   *   `replayPending: false` restores from COMMITTED rows only. SessionStart uses it because replay
+   *   is a WRITE, a write is a `ruflo memory store` process, and one of those alone costs more than
+   *   the entire SessionStart budget — so a restore that replayed would time out and report UNKNOWN
+   *   precisely when there was durable evidence to show. Pending work is REPORTED here and replayed
+   *   at the next capture boundary (Stop / PreCompact / SessionEnd) or by /checkpoint, which are the
+   *   boundaries that already own a write budget. The outbox's fsync-then-commit ordering and its
+   *   replay-required semantics are untouched: nothing is dropped, only deferred.
+   */
+  restoreLatest({ pageSize = 100, maxEntries = 10_000, maxOutputBytes = 64 * 1024, replayPending = true } = {}) {
     requirePositiveInteger(maxOutputBytes, 'maxOutputBytes');
-    this.replay();
+    if (replayPending) this.replay();
+    const pendingReplay = replayPending ? 0 : this.pendingReplayCount();
     const keys = this.listSnapshotKeys({ pageSize, maxEntries });
     const exact = this.retrieveSnapshots(keys);
     const restored = restoreProjectProgression(exact.snapshots, {
@@ -253,6 +342,8 @@ export class ProjectProgressionStore {
     if (!restored.ok) {
       const error = new Error('no coherent progression state could be restored');
       error.rejectedCandidates = rejectedCandidates;
+      error.structurallyEnumerated = keys.length;
+      error.pendingReplay = pendingReplay;
       throw error;
     }
     const payload = {
@@ -266,12 +357,14 @@ export class ProjectProgressionStore {
         exactRetrieved: keys.length,
         causallyStale: restored.causallyStale.length,
         rejectedCandidates,
+        readPath: this.lastReadPath,
+        pendingReplay,
       },
     };
     const rendered = JSON.stringify(payload);
     if (Buffer.byteLength(rendered, 'utf8') > maxOutputBytes) {
       throw new Error(`resume payload exceeds the ${maxOutputBytes}-byte output bound`);
     }
-    return { payload, rendered };
+    return { payload, rendered, pendingReplay };
   }
 }

package/plugin/scripts/ruvnet-gate1-pattern.mjs

@@ -0,0 +1,29 @@
+/**
+ * ruvnet-gate1-pattern.mjs — the ONE copy of ground-ruvnet.sh's "Gate 1" regex outside that file.
+ *
+ * ground-ruvnet.sh (POSIX/bash) and grounding-turn-mark.mjs (Node) cannot literally `import` one
+ * another's source — one is a shell script, the other is JS. The task this file exists for is
+ * explicit: "copy it verbatim ... do not redefine a second, drifting copy ... or keep it
+ * byte-identical with a test that fails if they diverge". A shared data file both languages could
+ * read was considered and rejected: ground-ruvnet.sh is a hot, heavily-tuned, every-prompt hook
+ * (see its own header on the 38s-regression bounded-read fix), and editing it to add a file-read
+ * indirection for this one string is exactly the kind of non-surgical touch that risks a working,
+ * extensively-measured script for a feature that does not need it to change at all.
+ *
+ * So the copy lives here, in JS, and tests/unit/ruvnet-gate1-pattern.test.mjs parses
+ * ground-ruvnet.sh's own "Gate 1" grep line and asserts this string matches it byte-for-byte. A
+ * future edit to either side that is not mirrored in the other goes red immediately, which is the
+ * actual guarantee "byte-identical with a test that fails if they diverge" asks for.
+ *
+ * SOURCE OF TRUTH: plugin/scripts/ground-ruvnet.sh, the line beginning
+ * `if printf '%s' "$TEXT" | grep -qiE '...'; then` under the "Gate 1: does the task touch the rUv
+ * ecosystem?" comment. Copied 2026-09-12, case-insensitive (`-i`) to match `grep -qiE`.
+ */
+export const RUVNET_GATE1_PATTERN =
+  '\\bruvnet\\b|\\bruflo\\b|\\bruvector\\b|\\brvf\\b|\\bagentdb\\b|\\bagenticow\\b|\\brulake\\b|\\bruview\\b|\\brupixel\\b|\\bruv-fann\\b|\\bagentic-flow\\b|\\bsynthlang\\b|\\bdspy\\b|\\bqudag\\b|\\bsafla\\b|\\bmetaharness\\b|\\bcve-bench\\b|\\bsparc\\b|\\bswarms?\\b|\\bclaude-flow\\b|\\brUv\\b';
+
+/** Case-insensitive, matching the shell side's `grep -qiE`. A fresh RegExp per call — `.test()` on a
+ *  shared `g`/`y` instance is stateful and a caller-shared singleton here would be a subtle footgun. */
+export function ruvnetGate1Matches(text) {
+  return new RegExp(RUVNET_GATE1_PATTERN, 'i').test(String(text ?? ''));
+}

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

@@ -1,11 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import {
   captureProjectTransition,
   hasProjectProgression,
 } from './project-progression-hook.mjs';
 import { createSessionSnapshot } from './session-snapshot-contract.mjs';
 import { projectDirectory } from './project-identity.mjs';
+import { buildProjectProgression } from './project-progression-producer.mjs';
+import { ProjectProgressionStore } from './project-progression-store.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+
+/**
+ * The capture boundary's whole budget. hooks.json declares 10s; this keeps the internal work well
+ * inside it so the host never has to kill us, and so a slow store degrades to "no snapshot this
+ * time" rather than to a hung turn. Capture is advisory: it fails open, always.
+ */
+export const CAPTURE_BUDGET_MS = 8_000;
 
 function regularOrAbsent(file) {
   try {
@@ -43,22 +54,118 @@ export function writeSessionSnapshot(projectDir, event) {
   }
 }
 
+/**
+ * A deadline-bounded `ruflo` runner. The store's own 120s per-call timeout is right for a deliberate
+ * CLI invocation and far too generous for a lifecycle hook, so the remaining budget caps every call.
+ */
+function boundedStoreFactory(deadlineAt) {
+  return (options) => new ProjectProgressionStore({
+    ...options,
+    runner: (binary, args, runOptions) => {
+      const remaining = deadlineAt - Date.now();
+      if (remaining < 1) throw new Error('capture budget exceeded');
+      const result = spawnSync(binary, args, {
+        ...runOptions,
+        timeout: Math.min(runOptions.timeout ?? remaining, remaining),
+        shell: false,
+      });
+      if (result.error) throw new Error(`capture budget exceeded: ${result.error.message}`);
+      return result;
+    },
+  });
+}
+
+/**
+ * THE AUTOMATIC CAPTURE BOUNDARY.
+ *
+ * Before this, `captureProjectTransition` could only run when a host payload already carried a
+ * `projectProgression` extension — and no host emits one, so nothing was ever captured. Now the
+ * producer BUILDS that extension from real sources (git, the work ledger, the owner's own
+ * `project-state-current` note, the prior head, and a bounded transcript reference) whenever the
+ * payload does not supply one. An explicitly supplied extension still wins: that is how
+ * /ruvnet-brain:checkpoint hands over a state the model actually wrote.
+ *
+ * Two things are deliberately NOT done here:
+ *   • `.swarm` is never created. Its absence means the project has not adopted the brain, and a
+ *     lifecycle hook that plants a store in every repository the user opens is trespass (see above).
+ *   • No exception escapes. A capture boundary that can fail a turn is worse than a missed snapshot.
+ */
 export function runSessionSnapshotHook(projectDir, event, {
   rawInput = '',
   host = process.env.RUVNET_HOOK_HOST || 'claude',
   captureProgression = captureProjectTransition,
+  produce = buildProjectProgression,
+  budgetMs = CAPTURE_BUDGET_MS,
+  now = Date.now,
 } = {}) {
   const metadataWritten = writeSessionSnapshot(projectDir, event);
   let payload;
   try { payload = rawInput ? JSON.parse(rawInput) : {}; } catch { payload = {}; }
-  if (!hasProjectProgression(payload)) {
-    return { metadataWritten, progressionCaptured: false, receipt: null };
+  const idle = { metadataWritten, progressionCaptured: false, receipt: null };
+
+  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 });
+    return { ...idle, progressionCaptured: true, receipt: result.receipt };
+  }
+
+  // A payload with no session identity is not a real lifecycle event (an empty `{}` from a probe,
+  // a malformed host). Capturing against an invented session id would fabricate a journal entry.
+  if (typeof payload.session_id !== 'string' || !payload.session_id) {
+    return { ...idle, skipped: 'no session identity in the host payload' };
+  }
+
+  let resolution;
+  try { resolution = resolveProjectStore({ projectDir }); } catch {
+    return { ...idle, skipped: 'project store could not be resolved' };
   }
-  if (payload.hook_event_name !== event) {
-    throw new Error(`progression boundary mismatch: expected ${event}, received ${payload.hook_event_name}`);
+  if (!fs.existsSync(path.dirname(resolution.canonicalAgentDbPath))) {
+    return { ...idle, skipped: 'project has not adopted the canonical store' };
+  }
+
+  const deadlineAt = now() + budgetMs;
+  const storeFactory = boundedStoreFactory(deadlineAt);
+
+  // Commit anything a previously interrupted session left durable-but-uncommitted. SessionStart is
+  // forbidden from doing this (ADR-073 §5) because replay is a write; a capture boundary already
+  // owns a write budget, so this is where that debt is settled.
+  let replayed = 0;
+  try {
+    replayed = storeFactory({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath }).replay().length;
+  } catch { /* the new capture below is still worth attempting */ }
+
+  let produced;
+  try {
+    produced = produce({ resolution, payload, host, trigger: event });
+  } catch (error) {
+    return { ...idle, replayed, skipped: `producer failed: ${error.message}` };
+  }
+  if (produced.skipped) return { ...idle, replayed, skipped: produced.skipped.reason };
+
+  let result;
+  try {
+    result = captureProgression({
+      host,
+      payload: { ...payload, hook_event_name: event, projectProgression: produced.projectProgression },
+      projectDir,
+      storeFactory,
+    });
+  } catch (error) {
+    // NOT LOST — DEFERRED. capture() fsyncs the snapshot to the durable outbox BEFORE it writes to
+    // the store, so a budget overrun here leaves the evidence on disk and the next capture boundary
+    // (or /checkpoint) commits it. Reporting that plainly is the whole difference between a bounded
+    // hook and a lossy one, so the reason is returned rather than thrown at a lifecycle boundary.
+    return { ...idle, replayed, skipped: `capture deferred: ${error.message}` };
   }
-  const result = captureProgression({ host, payload, projectDir });
-  return { metadataWritten, progressionCaptured: true, receipt: result.receipt };
+  return {
+    metadataWritten,
+    progressionCaptured: true,
+    replayed,
+    receipt: result.receipt,
+    provenance: produced.provenance,
+  };
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
@@ -68,7 +175,8 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-
   try {
     runSessionSnapshotHook(projectDirectory(), process.argv[2] || 'SessionEnd', { rawInput });
   } 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.
     process.stderr.write(`[project-progression] ${error.message}\n`);
-    process.exitCode = 1;
   }
 }

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// session-start-budget.mjs — the DERIVED-SUM latency contract for SessionStart (ADR-067 pattern,
+// added 2026-09-11 after two independent reviewers flagged the original per-stage timeouts as
+// unaccountable numbers with no relationship to the hook's own declared budget).
+//
+// Every stage the hook can run declares its OWN cost HERE, once. Nothing downstream invents a
+// second number: session-start-trace.mjs enforces these at runtime (skip-with-note on overrun),
+// and tests/unit/session-start-budget.test.mjs sums them and fails the build the moment the total
+// creeps past hooks.json's own declared SessionStart timeout — so a new stage, or a raised budget,
+// is a reviewable diff instead of a silent latency regression nobody notices until a stranger's
+// session hangs.
+//
+// `restore` is continuity's project-progression restore (plugin/scripts/project-progression-
+// session-start.mjs) — accounted for HERE because it shares this hook's wall-clock budget, but the
+// stage itself is NOT this lane's code and is not wrapped by session-start-trace.mjs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const HOOKS_JSON_PATH = path.resolve(HERE, '..', 'hooks', 'hooks.json');
+
+/** SessionStart's own declared timeout in ms, read LIVE from hooks.json — never hand-copied, so a
+ * future retiming there is the one and only place this contract has to agree with. */
+export function sessionStartTimeoutMs(hooksJsonPath = HOOKS_JSON_PATH) {
+  const doc = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+  const entry = doc?.hooks?.SessionStart?.[0]?.hooks?.[0];
+  const timeoutSec = typeof entry?.timeout === 'number' ? entry.timeout : null;
+  if (!timeoutSec) throw new Error(`${hooksJsonPath}: could not read SessionStart's declared timeout`);
+  return timeoutSec * 1000;
+}
+
+// Per-stage budgets, ms. Every stage session-start-core.mjs (or continuity's restore) can run
+// appears here exactly once. Reviewer-mandated ceilings: restore <= 1000, banner <= 200.
+export const STAGE_BUDGETS_MS = {
+  restore: 1000,          // continuity lane's project-progression restore — NOT this lane's code
+  misc: 250,              // settings/nightly/health/console-offer/auto-pref/star — small fs reads
+  // The cache read itself is budgeted at 100ms internally (session-start-issue-alert.mjs's own
+  // ISSUE_POINTER_BUDGET_MS, per correction #2's exact wording); this stage's total also carries
+  // the repo-scoping git check (session-start-repo-identity.mjs), bounded separately at up to
+  // 1000ms under real load — never a network call either way.
+  'issue-pointer': 1100,
+  'signal-surface': 400,  // bounded CI-signal transition poll (see session-start-signals.mjs)
+  'router-nudge': 50,     // one fs.existsSync + at-most-one-time write
+  '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
+  banner: 200,            // version/readiness/health banner assembly — pure fs reads, no subprocess
+};
+
+export function sumBudgetsMs(budgets = STAGE_BUDGETS_MS) {
+  return Object.values(budgets).reduce((sum, ms) => sum + ms, 0);
+}
+
+// Measured node process boot (interpreter start + module graph load) BEFORE any stage code runs —
+// real, unavoidable overhead the stage budgets above do not (and must not) account for. A named
+// constant, not folded silently into one stage's budget, so a boot-time regression shows up as its
+// own line instead of quietly eating an unrelated stage's headroom.
+export const MEASURED_NODE_BOOT_MS = 250;