ruvnet-brain 4.6.4 → 4.7.1

package/plugin/scripts/learning-store.mjs

@@ -1,15 +1,13 @@
 // Canonical workflow observations; existing Ruflo is the sole writer, never the legacy JSON hook store.
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { resolveProjectStore } from './project-store-resolver.mjs';
-import { withProgressionReader } from './project-progression-reader.mjs';
-import { rufloRunDir } from './project-progression-store.mjs';
-import { rufloInvocation } from './ruflo-bin.mjs';
+import { rufloInvocation, rufloRunDir, resolveRuflo } from './ruflo-bin.mjs';
 import { loadRuntimePreferences } from './runtime-preferences.mjs';
-import { loadNodeSqlite } from './node-sqlite.mjs';
-import { safeQueue, writeAtomic } from './learning-queue.mjs';
+import { learningContext } from './runtime-preferences.mjs';
 
 export const LEARNING_NAMESPACE = 'learning-observations';
 export function learningTarget(context, { env = process.env, explicitLegacyApply = false } = {}) {
@@ -18,7 +16,8 @@ export function learningTarget(context, { env = process.env, explicitLegacyApply
   const root = path.join(context.home, '.claude', 'global-memory');
   const chosen = loadRuntimePreferences({ env, cwd: context.projectDir }).values.learningScope === 'user';
   if (!chosen && !explicitLegacyApply) throw new Error('user learning requires persisted user consent or explicit legacy Apply');
-  safeQueue({ scope: 'user', home: context.home, queueDir: root });
+  const rootStat = fs.lstatSync(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('user learning root is not a real directory');
   const db = path.join(root, '.swarm', 'memory.db');
   if (!fs.lstatSync(db).isFile()) throw new Error('user store not adopted');
   const resolved = resolveProjectStore({ projectDir: root, requestedStorePath: db, gitTimeoutMs: 1000 });
@@ -26,80 +25,91 @@ export function learningTarget(context, { env = process.env, explicitLegacyApply
   return resolved.canonicalAgentDbPath;
 }
 
-export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000 } = {}) {
+export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000, maxStepMs = 6000 } = {}) {
   const remaining = deadline - Date.now();
   if (remaining <= 0) throw new Error('learning deadline exhausted');
-  const cwd = rufloRunDir(db, { root: env.RUVNET_RUFLO_CWD_ROOT || path.join(env.HOME, '.cache', 'ruvnet-brain', 'learning-ruflo') });
+  const cwd = rufloRunDir(db, { root: env.RUVNET_RUFLO_CWD_ROOT || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.cache', 'ruvnet-brain', 'learning-ruflo') });
   try {
     const invocation = rufloInvocation(binary, args);
     return spawnSync(invocation.executable, invocation.args, { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' },
-      encoding: 'utf8', shell: false, timeout: Math.min(6000, remaining), killSignal: 'SIGKILL', maxBuffer: 65536, windowsHide: true });
+      encoding: 'utf8', shell: false, timeout: Math.min(maxStepMs, remaining), killSignal: 'SIGKILL', maxBuffer: 65536, windowsHide: true });
   } finally { fs.rmSync(cwd, { force: true, recursive: true }); }
 }
 
-export function recordLearningObservation(binary, context, file, record, row, options = {}) {
+/**
+ * One observation, written DIRECTLY through `ruflo memory store` and proven by exact-key CLI readback.
+ * No local queue, no worker, no replay (owner ruling 2026-10-12): a failure throws to the caller, which
+ * records it in the hook-failures ledger so SessionStart reports it.
+ */
+export function recordLearningObservation(binary, context, { tool, action, session = '' }, options = {}) {
   const db = learningTarget(context, options);
-  const key = 'workflow-' + createHash('sha256').update(path.basename(file) + ':' + record.key).digest('hex');
-  const value = JSON.stringify({ schemaVersion: 1, tool: row.tool, action: row.action, scope: context.scope,
+  // DETERMINISTIC per (session, tool, action) (review N1): with --no-upsert, rUv's store itself dedupes, so a
+  // session holds at most one row per distinct pair and concurrent writers of the same pair collapse.
+  const key = 'workflow-' + createHash('sha256').update(JSON.stringify([session, tool, action])).digest('hex');
+  const value = JSON.stringify({ schemaVersion: 1, tool, action, scope: context.scope,
     authoritative: false, provenance: 'system-observation', outcome: 'host-reported-success' });
   const run = args => { if (options.allowed && !options.allowed()) throw new Error('learning consent changed'); return runLearningRuflo(binary, args, db, options); };
-  const existing = withProgressionReader(db, reader => reader.readContent(LEARNING_NAMESPACE, key));
-  if (!(existing.ok && existing.value === value)) {
-    const stored = run(['memory', 'store', '--key', key, '--value', value, '--namespace', LEARNING_NAMESPACE,
-      '--no-upsert', '--provenance', 'system_observation', '--path', db]);
-    if (stored.error || stored.status !== 0) throw new Error('canonical observation write failed');
-  }
+  const stored = run(['memory', 'store', '--key', key, '--value', value, '--namespace', LEARNING_NAMESPACE,
+    '--no-upsert', '--provenance', 'system_observation', '--path', db]);
   const retrieved = run(['memory', 'retrieve', '--key', key, '--namespace', LEARNING_NAMESPACE, '--value-only', '--path', db]);
-  if (retrieved.error || retrieved.status !== 0 || retrieved.stdout.trim() !== value) throw new Error('canonical exact CLI readback failed');
-  const independent = withProgressionReader(db, reader => reader.readContent(LEARNING_NAMESPACE, key));
-  if (!independent.ok || independent.value !== value) throw new Error('canonical independent row readback failed');
-  return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true, independentRow: true };
+  const exact = !retrieved.error && retrieved.status === 0 && String(retrieved.stdout || '').trim() === value;
+  // A refused store whose key already holds these exact bytes is the dedupe working, not a failure.
+  if (stored.error || stored.status !== 0) {
+    if (exact) return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true, alreadyStored: true };
+    throw new Error(`ruflo memory store refused the observation: ${String(stored.stderr || stored.stdout || stored.error?.message || '').trim().slice(0, 160)}`);
+  }
+  if (!exact) throw new Error('canonical exact CLI readback failed');
+  return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true };
 }
 
-export function learningStoreStatus(db) {
-  const rows = withProgressionReader(db, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).length);
-  if (!rows.ok) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
-  const sqlite = loadNodeSqlite(); let connection;
+/** Observation count through `ruflo memory list` (no direct SQLite). Unknown stays unknown. */
+export function learningStoreStatus(db, { binary = resolveRuflo(), env = process.env } = {}) {
+  if (!binary) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
   try {
-    connection = new sqlite.DatabaseSync(db, { readOnly: true });
-    const present = name => !!connection.prepare('SELECT 1 FROM sqlite_master WHERE type=? AND name=?').get('table', name);
-    const patterns = present('reasoning_patterns') ? connection.prepare('SELECT count(*) AS n FROM reasoning_patterns WHERE json_valid(metadata) AND json_extract(metadata,?)=?').get('$.namespace', LEARNING_NAMESPACE).n : 0;
-    const at = present('distill_state') ? connection.prepare('SELECT last_run_at AS at FROM distill_state WHERE namespace=?').get(LEARNING_NAMESPACE)?.at : null;
-    return { known: true, observations: rows.value, patterns, lastDistillAt: at ?? null };
-  } catch { return { known: false, observations: rows.value, patterns: null, lastDistillAt: null }; }
-  finally { connection?.close(); }
+    const listed = runLearningRuflo(binary, ['memory', 'list', '--namespace', LEARNING_NAMESPACE, '--limit', '100000', '--format', 'json', '--path', db], db, { env });
+    const text = String(listed.stdout || ''); const at = text.indexOf('[');
+    if (listed.status !== 0 || at < 0) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
+    return { known: true, observations: JSON.parse(text.slice(at)).length, patterns: null, lastDistillAt: null };
+  } catch { return { known: false, observations: 0, patterns: null, lastDistillAt: null }; }
 }
 
-/** Existing $0 structural distiller, with a verified native WAL-safe snapshot before mutation. */
+/** `ruflo memory backup` then `ruflo memory distill run`; both are rUv's own commands. */
 export function distillLearning(binary, context, options = {}) {
-  const db = learningTarget(context, options); const before = learningStoreStatus(db);
-  if (!before.known) throw new Error('distillation baseline unavailable');
-  if (options.automatic && before.lastDistillAt !== null && Date.now() - before.lastDistillAt < 3600_000) {
-    return { db, completed: false, deferred: 'automatic cadence: at most hourly', patternDelta: 0, ratifiedLessons: 0 };
-  }
-  const backupDir = path.join(path.dirname(db), 'learning-backups');
+  const db = learningTarget(context, options);
   const run = args => { if (options.allowed && !options.allowed()) throw new Error('learning consent changed'); return runLearningRuflo(binary, args, db, options); };
-  if (options.allowed && !options.allowed()) throw new Error('learning consent changed');
-  safeQueue({ scope: 'project', projectDir: path.dirname(path.dirname(db)), queueDir: backupDir }, true);
-  const prior = new Set(fs.readdirSync(backupDir));
-  const backup = run(['memory', 'backup', '--db', db, '--dir', backupDir, '--keep', '3', '--verbose']);
+  const backupDir = path.join(path.dirname(db), 'learning-backups');
+  fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+  const backup = run(['memory', 'backup', '--db', db, '--dir', backupDir, '--keep', '3']);
   if (backup.error || backup.status !== 0) throw new Error('distillation backup failed');
-  if (!backup.stdout.includes('memory DB backed up → ') || backup.stdout.includes('byte-copy')) throw new Error('native online backup mode unverified');
-  const images = fs.readdirSync(backupDir).filter(name => name.endsWith('.db') && !prior.has(name));
-  if (images.length !== 1) throw new Error('fresh distillation snapshot absent');
-  const image = path.join(backupDir, images[0]);
-  fs.chmodSync(image, 0o600);
-  // The source-bound verbose marker above distinguishes native online backup from
-  // Ruflo's byte-copy fallback. Row verification is additional observation evidence,
-  // not a claim that this subset alone proves whole-database rollback.
-  const source = withProgressionReader(db, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).map(key => [key, reader.readContent(LEARNING_NAMESPACE, key)]));
-  const copy = withProgressionReader(image, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).map(key => [key, reader.readContent(LEARNING_NAMESPACE, key)]));
-  if (!source.ok || !copy.ok || JSON.stringify(source.value) !== JSON.stringify(copy.value)) throw new Error('distillation snapshot row verification failed');
-  writeAtomic(path.join(backupDir, 'latest-receipt.json'), JSON.stringify({ db, before, snapshot: image, providerMode: 'native-online-backup', observationsVerified: true, retainedSnapshots: 3, restore: 'automatic exact restore unavailable' }));
   const distilled = run(['memory', 'distill', 'run', '--db', db, '--namespace', LEARNING_NAMESPACE,
     '--max-entries', '8', '--judge', 'structural', '--budget-usd', '0']);
-  const after = learningStoreStatus(db);
-  return { db, before, after, completed: !distilled.error && distilled.status === 0,
-    patternDelta: before.known && after.known ? after.patterns - before.patterns : null,
-    snapshot: image, ratifiedLessons: 0 };
+  return { db, completed: !distilled.error && distilled.status === 0, ratifiedLessons: 0 };
+}
+
+/**
+ * Distill the observation rows with rUv's own `ruflo memory distill run` (incremental cursor, $0
+ * structural judge), bounded. Run detached at SessionEnd/PreCompact (review M3). No backup on this path:
+ * a whole-DB copy per session end costs more than the distill. A failure throws to the caller (ledger).
+ */
+export function distillObservations(binary, context, options = {}) {
+  const db = learningTarget(context, options);
+  const r = runLearningRuflo(binary, ['memory', 'distill', 'run', '--db', db, '--namespace', LEARNING_NAMESPACE,
+    '--max-entries', '500', '--judge', 'structural', '--budget-usd', '0'], db, { ...options, maxStepMs: 60_000, deadline: Date.now() + 60_000 });
+  if (r.error || r.status !== 0) throw new Error(`ruflo memory distill run did not complete (${r.error?.code || `exit ${r.status}`})`);
+  return { db, completed: true };
+}
+
+/** What the console shows: consent, target and the observation count. There is no local queue. */
+export function observeLearning(options = {}) {
+  const env = options.env ?? process.env;
+  const context = learningContext(options);
+  const result = { ...context, queueDepth: 0, queueKnown: true, legacyUserDepth: 0, legacyUserKnown: true, lastTrainSeconds: null, trajectories: 0, statusKnown: false };
+  if (!context.enabled) return result;
+  try {
+    result.learningDb = learningTarget(context, { env });
+    const state = learningStoreStatus(result.learningDb, { env });
+    result.statusKnown = state.known; result.trajectories = state.observations; result.observations = state.observations;
+    result.patterns = state.patterns; result.lastDistillAt = state.lastDistillAt;
+  } catch { /* Missing consent/store/readback remains unknown. */ }
+  return result;
 }

package/plugin/scripts/node-sqlite.mjs

@@ -4,7 +4,7 @@
  * WHY (measured 2026-10-01, Node 22.13.1 locally and Node 22 on the Linux CI full suite, run 36894944735):
  * on Node 22 the first load of `node:sqlite` prints
  *   (node:PID) ExperimentalWarning: SQLite is an experimental feature and might change at any time
- * to stderr. SessionStart reads the store through project-progression-reader.mjs, so every SessionStart
+ * to stderr. SessionStart once read the store through a native reader, so every SessionStart
  * in an adopted git project on Node 22 carried that line — hook noise a customer sees on every session.
  * Node 24 does not warn, which is why the owner's machine never showed it.
  *

package/plugin/scripts/ruflo-bin.mjs

@@ -2,7 +2,7 @@
  * ruflo-bin.mjs — the ONE place this repo decides WHERE the global `ruflo` binary is.
  *
  * WHY THIS FILE EXISTS. Issues #99 and #105 are one defect filed twice: `scripts/distill-project.mjs`
- * and `plugin/scripts/learn-flush.mjs` each hardcoded `~/.npm-global/bin/ruflo` — the owner's npm
+ * and the learning flusher each hardcoded `~/.npm-global/bin/ruflo` — the owner's npm
  * prefix, nobody else's. On a Homebrew, nvm, Volta, or plain `npm -g` install that path does not
  * exist, so #99 died with "ruflo is not at ~/.npm-global/bin/ruflo" and #105 failed every feed
  * silently — both on machines where ruflo was installed and sitting on PATH the whole time.
@@ -99,3 +99,73 @@ export function resolveRuflo({ env = process.env, home = os.homedir() } = {}) {
  */
 export const RUFLO_MISSING = 'ruflo was not found in ~/.npm-global/bin or anywhere on your PATH'
   + ' — install it with `npm i -g ruflo@latest`, or set RUFLO_BIN to its full path';
+
+// ── Private per-project ruflo working directories ──
+import crypto from 'node:crypto';
+
+/**
+ * The working directory ruflo runs in. ruflo writes into its cwd on every invocation even when --path
+ * names the store (measured 2026-10-01, ruflo 3.49.0): `.claude/`, `.claude-flow/`, `ruvector.db`, and
+ * `<cwd>/.swarm/` holding hnsw.metadata.json — the stored snapshot CONTENT — which it also LOADS when it
+ * finds one there (ruflo/v3/@claude-flow/cli/src/memory/memory-initializer.ts: getMemoryRoot() = cwd).
+ * So the cwd must be:
+ *  - never the project tree (it changed the customer's working tree and broke no-op capture detection),
+ *    never inside `.swarm` (nested `.swarm/.swarm`);
+ *  - PER PROJECT (one shared dir would pool every project's snapshot text and let one project load
+ *    another's metadata);
+ *  - private and ours: under the Brain's own home (never a shared /tmp name another user could pre-create
+ *    or symlink), every directory we create checked to be a real directory, owned by us, mode 0700.
+ * Every ruflo call carries --path, so the store it reads and writes is unaffected by the cwd.
+ */
+export function rufloScratchRoot(env = process.env) {
+  if (env.RUVNET_RUFLO_CWD_ROOT) return path.resolve(env.RUVNET_RUFLO_CWD_ROOT);
+  return path.join(env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'), 'ruflo-cwd');
+}
+
+/** Create-or-verify one private directory: a real directory (not a link), owned by us, mode 0700. */
+export function ensurePrivateDir(dir) {
+  try { fs.mkdirSync(dir, { mode: 0o700 }); } catch (error) { if (error?.code !== 'EEXIST') throw error; }
+  const stat = fs.lstatSync(dir);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`ruflo scratch directory ${dir} is not a real directory (symlink or file); refusing to use it`);
+  }
+  if (process.platform !== 'win32') {
+    if (stat.uid !== process.getuid()) {
+      throw new Error(`ruflo scratch directory ${dir} is owned by uid ${stat.uid}, not ${process.getuid()}; refusing to use it`);
+    }
+    if ((stat.mode & 0o777) !== 0o700) {
+      fs.chmodSync(dir, 0o700);
+      if ((fs.lstatSync(dir).mode & 0o777) !== 0o700) throw new Error(`ruflo scratch directory ${dir} could not be made private (0700)`);
+    }
+  }
+  return dir;
+}
+
+export function rufloCwdFor(storePath, { root = rufloScratchRoot() } = {}) {
+  const projectKey = crypto.createHash('sha256').update(path.resolve(storePath)).digest('hex').slice(0, 32);
+  fs.mkdirSync(path.dirname(root), { recursive: true });
+  ensurePrivateDir(root);
+  return ensurePrivateDir(path.join(root, projectKey));
+}
+
+const RUFLO_CWD_ARTIFACTS = Object.freeze(['.swarm', '.claude', '.claude-flow', 'ruvector.db']);
+const STALE_RUN_MS = 3_600_000;
+
+/**
+ * One ruflo invocation's working directory: a fresh private `run-*` directory inside the project's
+ * scratch dir, removed again by the caller after the call. ruflo copies every snapshot it touches into
+ * `<cwd>/.swarm/hnsw.metadata.json`; with one cwd per call that copy never accumulates (4.4.0 kept one
+ * per project that grew without bound and outlived the project). Also clears what 4.4.0 left directly
+ * in the project scratch dir and any `run-*` older than an hour (a call killed before its cleanup).
+ */
+export function rufloRunDir(storePath, { root = rufloScratchRoot(), now = Date.now() } = {}) {
+  const projectScratch = rufloCwdFor(storePath, { root });
+  for (const name of fs.readdirSync(projectScratch)) {
+    const entry = path.join(projectScratch, name);
+    let stat;
+    try { stat = fs.lstatSync(entry); } catch { continue; }
+    const stale = name.startsWith('run-') && stat.isDirectory() && now - stat.mtimeMs > STALE_RUN_MS;
+    if (RUFLO_CWD_ARTIFACTS.includes(name) || stale) fs.rmSync(entry, { recursive: true, force: true });
+  }
+  return fs.mkdtempSync(path.join(projectScratch, 'run-'));
+}

package/plugin/scripts/ruflo-memory-hooks.mjs

@@ -0,0 +1,204 @@
+/**
+ * Lifecycle project memory by CALLING Ruflo, never by reimplementing it (owner ruling 2026-10-12).
+ *
+ * Replaces the hand-rolled progression store / outbox / capture queue on the hook path. Measured on a
+ * clone of the owner's store: 1,763 cumulative snapshots (751 MB), a 3.38 GB outbox and 36k queued
+ * jobs made Stop, PreCompact and SessionEnd run to the watchdog at 8.5 s. Here every operation is
+ * one bounded `ruflo memory store|retrieve|list` call (rUv's documented pattern: exact keys,
+ * explicit --namespace, `--path` to the project store), so cost no longer grows with history.
+ *
+ *  • checkpoint(): PreCompact/SessionEnd store one small, append-only `project-state-auto-<ms>` row
+ *    and read it back by exact key. It never overwrites the owner's `project-state-current-*` notes.
+ *  • restore():    SessionStart retrieves the newest `project-state-current-*` (and a newer auto
+ *    checkpoint, if any) by exact key, plus a bounded list of `lessons` keys.
+ * `.swarm` is never created: its absence means the project has not adopted the brain.
+ */
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { execFile, execFileSync, spawnSync } from 'node:child_process';
+import os from 'node:os';
+import { resolveRuflo, rufloRunDir, rufloScratchRoot } from './ruflo-bin.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { checkpointNamespaces, newestOfFamily } from './checkpoint-keys.mjs';
+
+export const CURATED_PREFIX = 'project-state-current-';
+export const AUTO_PREFIX = 'project-state-auto-';
+
+/**
+ * The SAME store and namespace turn capture uses (review M2): the canonical project's `.swarm/memory.db`,
+ * which a linked git worktree shares with its main checkout. Every git call is bounded by the deadline.
+ */
+export function projectStore(projectDir, { deadlineAt = Date.now() + 3000 } = {}) {
+  let root = projectDir; let db = path.join(projectDir, '.swarm', 'memory.db');
+  try {
+    const gitTimeoutMs = Math.max(1, Math.min(1000, Math.floor(deadlineAt - Date.now())));
+    const resolved = resolveProjectStore({ projectDir, gitTimeoutMs, deadlineAt });
+    root = resolved.projectRoot; db = resolved.canonicalAgentDbPath;
+  } catch { /* unresolvable (or out of budget): treated as not adopted below only if no store exists here */ }
+  return { root, db, adopted: fs.existsSync(db), namespace: path.basename(root) };
+}
+
+/**
+ * The spawn options every ruflo call here uses. `--path` pins the store, so the working directory only receives
+ * what ruflo writes beside itself (`ruvector.db`, `.swarm/hnsw.*`, verified on 3.56.9). Run it in a fresh private
+ * scratch dir, never the project (where ruflo loaded the project's own .swarm index: median 1729 ms vs 1067 ms
+ * measured for the same list), and never let a hook call start the background daemon.
+ */
+export function rufloSpawnOptions(db, env = process.env) {
+  let cwd;
+  try { cwd = rufloRunDir(db, { root: rufloScratchRoot(env) }); } catch { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-ruflo-')); }
+  return { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' }, cleanup: () => { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later as a stale run- dir */ } } };
+}
+
+/** One `ruflo memory <args>` call, bounded by the caller's deadline. Resolves, never rejects. */
+export function rufloMemory(args, { db, env = process.env, bin = resolveRuflo({ env }), deadlineAt = Date.now() + 3000 } = {}) {
+  const timeout = Math.max(1, Math.floor(deadlineAt - Date.now()));
+  return new Promise((resolve) => {
+    if (!bin) return resolve({ ok: false, stdout: '', error: 'global Ruflo unavailable' });
+    const spawnAt = rufloSpawnOptions(db, env);
+    execFile(bin, ['memory', ...args, '--path', db], { cwd: spawnAt.cwd, env: spawnAt.env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
+      // The ledger gets a fixed reason, never execFile's message (it embeds the whole argv: value, db path).
+      (error, stdout) => { spawnAt.cleanup(); resolve({ ok: !error, stdout: String(stdout || ''), error: error ? (error.killed ? 'timed out' : `ruflo memory ${args[0]} exited ${error.code ?? 'abnormally'}`) : null }); });
+  });
+}
+
+function parseJson(text) {
+  const at = [text.indexOf('['), text.indexOf('{')].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+  if (at === undefined) return null;
+  try { return JSON.parse(text.slice(at)); } catch { return null; }
+}
+const entriesOf = (json) => (Array.isArray(json) ? json : json?.entries || json?.results || []);
+
+async function listKeys(namespace, options, limit = 1000) {
+  const r = await rufloMemory(['list', '-n', namespace, '--limit', String(limit), '--format', 'json'], options);
+  return r.ok ? entriesOf(parseJson(r.stdout)).filter((e) => typeof e?.key === 'string') : null;
+}
+const retrieve = async (key, namespace, options) => {
+  const r = await rufloMemory(['retrieve', '--key', key, '-n', namespace, '--value-only'], options);
+  return r.ok ? r.stdout.trim() : null;
+};
+
+function gitFacts(root, deadlineAt) {
+  const git = (args) => {
+    const timeout = Math.min(500, Math.floor(deadlineAt - Date.now()));
+    if (timeout < 1) return 'unmeasured';
+    try { return execFileSync('git', args, { cwd: root, encoding: 'utf8', timeout, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return 'unmeasured'; }
+  };
+  return { branch: git(['rev-parse', '--abbrev-ref', 'HEAD']), head: git(['rev-parse', '--short', 'HEAD']) };
+}
+
+/** PreCompact / SessionEnd: store one small checkpoint and prove it by exact-key readback. */
+export async function checkpoint({ projectDir, event, payload = {}, env = process.env, bin, deadlineAt = Date.now() + 7000, now = Date.now } = {}) {
+  if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') return { stored: false, skipped: 'RUVNET_TURN_CAPTURE=off' };
+  const store = projectStore(projectDir, { deadlineAt });
+  if (!store.adopted) return { stored: false, skipped: 'project has not adopted a .swarm/memory.db' };
+  // A short session hash keeps two sessions' same-millisecond checkpoints apart; --no-upsert makes a
+  // collision a refusal (ledger row) instead of a silent overwrite (review m1).
+  const sid = crypto.createHash('sha256').update(String(payload.session_id ?? process.pid)).digest('hex').slice(0, 8);
+  const key = `${AUTO_PREFIX}${now()}-${sid}`;
+  const value = JSON.stringify({ kind: 'automatic-checkpoint', event, session: payload.session_id ?? null,
+    at: new Date(now()).toISOString(), ...gitFacts(projectDir, deadlineAt) });
+  const options = { db: store.db, env, bin, deadlineAt };
+  const stored = await rufloMemory(['store', '--key', key, '-n', store.namespace, '--value', value, '--no-upsert'], options);
+  if (!stored.ok) return { stored: false, key, skipped: `store failed: ${stored.error}` };
+  const readBack = await retrieve(key, store.namespace, options);
+  return { stored: true, key, namespace: store.namespace, verified: readBack === value };
+}
+
+/** First page per namespace; ruflo answers it newest-first by createdAt, which restore() verifies, never assumes. */
+export const RESTORE_FAST_LIMIT = 100;
+/** Fallback page when the first page cannot prove where the newest checkpoint is. */
+export const RESTORE_FALLBACK_LIMIT = 5000;
+
+/**
+ * What one listed page proves. `ordered`: createdAt strictly non-increasing, so every row NOT on the page was
+ * created no later than `floor` (the page's oldest createdAt). `complete`: the page is shorter than the limit,
+ * so it is the whole namespace.
+ */
+export function pageFacts(rows, limit) {
+  if (!rows) return { listed: false };
+  const at = rows.map((e) => Number(e.createdAt));
+  const ordered = at.every(Number.isFinite) && at.every((t, i) => i === 0 || t <= at[i - 1]);
+  return { listed: true, ordered, complete: rows.length < limit, floor: at.length ? at[at.length - 1] : -Infinity };
+}
+
+/**
+ * A namespace still has to be read further only if a checkpoint newer than `best` could be hiding beyond its
+ * page: the page is partial AND (its order is unproven OR its floor is newer than the best checkpoint found).
+ * A checkpoint key carries its write time, so one created before `floor` carries an epoch-ms at or before it.
+ */
+export function needsFallback(facts, best) {
+  if (!facts.listed) return true;
+  if (facts.complete) return false;
+  if (!facts.ordered) return true;
+  return !best || facts.floor > best.ms;
+}
+
+/** SessionStart: newest curated checkpoint (+ newer auto checkpoint) and lesson keys, by exact key. */
+export async function restore({ cwd, env = process.env, bin, deadlineAt = Date.now() + 3000 } = {}) {
+  const store = projectStore(cwd, { deadlineAt });
+  if (!store.adopted) return { status: 'unavailable', context: '' };
+  const options = { db: store.db, env, bin, deadlineAt };
+  // Dirname, its lowercase form and default: `ruflo memory list -n` is case-sensitive and owners write both.
+  const namespaces = checkpointNamespaces(store.root);
+  // Fast path: ONE small newest-first page per namespace, all in parallel with the lessons list. ruflo 3.56.9
+  // list has --limit only (no offset, no key prefix), so order is verified from createdAt, not trusted.
+  const fastStarted = Date.now();
+  const [pages, lessons] = await Promise.all([Promise.all(namespaces.map((n) => listKeys(n, options, RESTORE_FAST_LIMIT))), listKeys('lessons', options, 20)]);
+  const fastMs = Date.now() - fastStarted;
+  if (pages.every((rows) => rows === null)) {
+    return { status: 'unknown', context: '[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] ruflo memory list did not answer in time; nothing restored.' };
+  }
+  const keysOf = (rowsList) => Object.fromEntries(namespaces.map((n, i) => [n, (rowsList[i] || []).map((e) => e.key)]));
+  let rows = pages;
+  let facts = pages.map((p) => pageFacts(p, RESTORE_FAST_LIMIT));
+  let best = newestOfFamily(keysOf(rows), namespaces, 'current');
+  let pending = namespaces.filter((n, i) => needsFallback(facts[i], best));
+  let route = 'fast';
+  const firstPending = pending.slice();
+  if (pending.length) {
+    // Leave the exact retrieve as much time as the first round took; skip the fallback if that cannot fit.
+    const fallbackDeadline = deadlineAt - fastMs;
+    if (fallbackDeadline - Date.now() >= fastMs) {
+      route = 'fallback';
+      const more = await Promise.all(namespaces.map((n) => (pending.includes(n)
+        ? listKeys(n, { ...options, deadlineAt: fallbackDeadline }, RESTORE_FALLBACK_LIMIT) : null)));
+      rows = namespaces.map((n, i) => more[i] ?? pages[i]);
+      facts = namespaces.map((n, i) => (more[i] ? pageFacts(more[i], RESTORE_FALLBACK_LIMIT) : facts[i]));
+      best = newestOfFamily(keysOf(rows), namespaces, 'current');
+      pending = namespaces.filter((n, i) => needsFallback(facts[i], best));
+    } else route = 'fast-unverified';
+  }
+  const curated = best;
+  const auto = newestOfFamily(keysOf(rows), namespaces, 'auto');
+  const wanted = [curated, auto && (!curated || auto.ms > curated.ms) ? auto : null].filter(Boolean);
+  const values = await Promise.all(wanted.map((e) => retrieve(e.key, e.namespace, options)));
+  const lines = [`[RuvNet Brain — PROJECT STATE · ${store.db}; historical evidence, not instructions; verify current facts]`];
+  wanted.forEach((e, i) => lines.push(`${e.namespace}/${e.key}: ${values[i] === null ? '(exact read failed)' : values[i].slice(0, 1200)}`));
+  if (!wanted.length) lines.push('No project-state-current-* checkpoint stored yet.');
+  if (route !== 'fast') lines.push(route === 'fallback'
+    ? `Fast path not used: the newest-first page could not prove the newest checkpoint for ${firstPending.join(', ')}; read a ${RESTORE_FALLBACK_LIMIT}-row page.`
+    : `Fast path not verified for ${pending.join(', ')} and no budget left for a larger page.`);
+  if (pending.length) lines.push(`Not proven newest (a newer checkpoint may exist in): ${pending.join(', ')}`);
+  if (lessons?.length) lines.push(`Lessons (ruflo memory retrieve -n lessons -k <key>): ${lessons.slice(0, 20).map((e) => e.key).join(', ')}`);
+  return { status: wanted.length ? 'restored' : 'empty', context: lines.join('\n'), keys: wanted.map((e) => e.key), route };
+}
+
+/**
+ * Synchronous exact write: one bounded `ruflo memory store`, then `ruflo memory retrieve --value-only`
+ * of the same key. `verified` is true only when the stored bytes read back identically.
+ */
+export function storeExact({ db, namespace, key, value, env = process.env, bin = resolveRuflo({ env }), timeoutMs = 6000, run = spawnSync } = {}) {
+  if (!bin) return { stored: false, verified: false, error: 'global Ruflo unavailable' };
+  const spawnAt = rufloSpawnOptions(db, env);
+  const options = { encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 8 * 1024 * 1024, cwd: spawnAt.cwd, env: spawnAt.env };
+  try {
+    const stored = run(bin, ['memory', 'store', '--key', key, '--value', value, '--namespace', namespace, '--path', db], options);
+    if (stored.error || stored.status !== 0) {
+      return { stored: false, verified: false, error: String(stored.stderr || stored.stdout || stored.error?.message || 'store failed').trim().slice(0, 200) };
+    }
+    const read = run(bin, ['memory', 'retrieve', '--key', key, '--namespace', namespace, '--value-only', '--path', db], options);
+    return { stored: true, verified: !read.error && read.status === 0 && String(read.stdout || '').trim() === value, key };
+  } finally { spawnAt.cleanup(); }
+}

package/plugin/scripts/runtime-preferences.mjs

@@ -290,7 +290,7 @@ if (process.argv.includes('--learning-scope')) {
 /**
  * WHERE THE LEARNER LIVES — ONE ANSWER, SHARED BY THE WRITER AND EVERY READER.
  *
- * ISSUE #139, filed by @ObiWanKenobi, and he is right about the shape. `learn-flush.mjs` resolves
+ * ISSUE #139, filed by @ObiWanKenobi, and he is right about the shape. the learning flusher resolved
  * the learning scope properly and then writes to `HOME` or `PROJECT` accordingly. The console read
  * the learner with a HARDCODED cwd — first `SYSTEM_HOME` (issue #136), then `process.cwd()` after
  * the fix. Both are hardcodes. Neither asks which scope is in effect.