ruvnet-brain 4.6.4 → 4.7.0

package/plugin/scripts/learn-capture.mjs

@@ -1,21 +1,37 @@
 #!/usr/bin/env node
-// PostToolUse captures only a fixed workflow vocabulary, then schedules bounded orphan recovery.
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID, createHash } from 'node:crypto';
+import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readStdinBounded } from './hook-input.mjs';
 import { learningContext } from './runtime-preferences.mjs';
-import { learningTarget } from './learning-store.mjs';
-import { safeQueue, safeAction, writeExclusive, takeQueueLock, releaseQueueLock, queueFiles } from './learning-queue.mjs';
+import { recordLearningObservation, distillObservations } from './learning-store.mjs';
+import { resolveRuflo } from './ruflo-bin.mjs';
+import { recordHookFailure } from './hook-failures.mjs';
+
+// Fixed vocabulary: arbitrary executable names, arguments, basenames and paths never persist.
+const verbs = new Set('git npm node python python3 cargo rustc go gh cd ls rg cat export mkdir rm cp mv bash sh curl wget npx ruflo'.split(' '));
+const subs = new Set('status diff log show add commit push pull fetch checkout switch branch test run install ci build check fmt clippy auth workflow release memory hooks'.split(' '));
+export function safeAction(tool, value) {
+  if (typeof value !== 'string') return null;
+  if (tool === 'Bash') {
+    const [verb, sub] = value.trim().split(/\s+/, 3);
+    if (!verbs.has(verb)) return 'command';
+    return subs.has(sub) ? `${verb} ${sub}` : verb;
+  }
+  if (!['Write', 'Edit', 'MultiEdit'].includes(tool)) return null;
+  // Legacy action is minimized again before invocation; no private basename reaches Ruflo argv.
+  return 'edit file';
+}
 
 /**
- * One PostToolUse observation. Since ADR-106 it runs IN-PROCESS from session-snapshot's PostToolUse
- * boundary (one registration instead of two); the script entry below stays for explicit invocation.
- * learningContext() owns consent and brain-off, so the fold keeps ADR-054's OFF contract.
+ * One PostToolUse observation, written DIRECTLY with `ruflo memory store` + exact-key readback (owner
+ * ruling 2026-10-12: no local queue, no flush worker, no replay). It runs in-process from
+ * session-snapshot's PostToolUse boundary. learningContext() owns consent and brain-off. A refused or
+ * unverified write is LOUD: one row in the hook-failures ledger, summarized at the next SessionStart.
  */
-export function captureLearning(input) {
+export function captureLearning(input, { env = process.env, binary = resolveRuflo({ env }), brainHome, detach = false } = {}) {
+  let tool; let action;
   try {
     const context = learningContext();
     if (!context.enabled || !input || typeof input !== 'object') return false;
@@ -28,48 +44,50 @@ export function captureLearning(input) {
     if (input.error || input.is_error === true || response?.error || response?.interrupted === true || response?.signal
       || response?.success === false || response?.is_error === true || response?.isError === true
       || [response?.exit_code, response?.exitCode, response?.status].some(value => Number.isInteger(value) && value !== 0)) return false;
-    const tool = input.tool_name;
+    tool = input.tool_name;
     if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(tool)) return false;
-    const action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
+    action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
     if (!action) return false;
-    const fresh = learningContext();
-    if (!fresh.enabled || fresh.queueDir !== context.queueDir) return false;
-    learningTarget(fresh); // Existing authorized user store is required before creating any user queue bytes.
-    const dir = safeQueue(fresh, true);
-    const sid = createHash('sha256').update(String(input.session_id || process.env.CLAUDE_SESSION_ID || 'default')).digest('hex').slice(0, 24);
-    writeExclusive(path.join(dir, `session-${sid}-${randomUUID()}.jsonl`), JSON.stringify({ tool, action }) + '\n');
-    // Per-scope lock in the flusher suppresses duplicate workers; capture never waits on the learner.
-    const token = takeQueueLock(fresh);
-    if (!token) return true;
-    const child = spawn(process.execPath, [fileURLToPath(new URL('./learn-flush.mjs', import.meta.url)), '--supervisor'], {
-      cwd: fresh.projectDir, detached: true, stdio: 'ignore', windowsHide: true, env: { ...process.env, RUVNET_LEARN_WORKER_TOKEN: token },
-    });
-    child.on('error', () => releaseQueueLock(fresh, token)); child.unref();
+    if (!binary) throw new Error('ruflo not found');
+    const observation = { tool, action, session: String(input.session_id || '') };
+    // Review M3: on the hook path the store + exact readback run in a detached, bounded child, so the
+    // tool call returns at once; that child writes the ledger row if the write is refused or unverified.
+    if (detach) return detachLearning('--observe', { env, brainHome, observation });
+    recordLearningObservation(binary, context, observation, { env, deadline: Date.now() + 6000 });
     return true;
-  } catch { return false; /* advisory transport; unsafe/malformed input produces no persisted payload */ }
+  } catch (error) {
+    if (tool && action) recordHookFailure({ hook: 'learn-capture', event: 'PostToolUse', error: String(error?.message || error).slice(0, 160) }, brainHome ? { brainHome } : undefined);
+    return false;
+  }
 }
 
-/**
- * Lifecycle recovery (formerly its own SessionStart/SessionEnd registration, ADR-106): when learning
- * is enabled, start learn-flush detached so an orphaned queue is drained by one finite worker. The
- * caller never waits; learn-flush owns the lock, the deadline and the consent re-checks.
- */
-export function scheduleLearningRecovery({ cwd = process.cwd(), env = process.env, spawnFn = spawn } = {}) {
+/** Detached, bounded child (`--observe` one observation, `--distill` the namespace). Only fixed-vocabulary fields cross. */
+export function detachLearning(mode, { env = process.env, brainHome, observation } = {}) {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), mode], { cwd: process.cwd(), detached: true, stdio: 'ignore', windowsHide: true,
+    env: { ...env, ...(observation ? { RUVNET_LEARN_OBSERVATION: JSON.stringify(observation) } : {}), ...(brainHome ? { RUVNET_BRAIN_HOME: brainHome } : {}) } });
+  child.unref();
+  return true;
+}
+
+function runDetached(mode) {
+  const fail = (error) => recordHookFailure({ hook: mode === '--distill' ? 'learn-distill' : 'learn-capture', event: mode === '--distill' ? 'SessionEnd' : 'PostToolUse', error: String(error?.message || error).slice(0, 160) });
   try {
-    const context = learningContext({ env, cwd });
-    if (!context.enabled) return false;
-    // Nothing queued, nothing to recover. Spawning anyway cost a process at every session boundary and,
-    // on Windows, a live worker holds the project directory as its cwd (EBUSY on delete/move).
-    if (queueFiles(context, { limit: 1, deadline: Date.now() + 100 }).length === 0) return false;
-    const child = spawnFn(process.execPath, [fileURLToPath(new URL('./learn-flush.mjs', import.meta.url))], {
-      cwd, detached: true, stdio: 'ignore', windowsHide: true, env });
-    child.on?.('error', () => {}); child.unref?.();
-    return true;
-  } catch { return false; }
+    const context = learningContext(); // consent is re-read: a withdrawn consent writes nothing
+    if (!context.enabled) return;
+    const binary = resolveRuflo({ env: process.env });
+    if (!binary) throw new Error('ruflo not found');
+    if (mode === '--distill') { distillObservations(binary, context, { env: process.env }); return; }
+    const o = JSON.parse(process.env.RUVNET_LEARN_OBSERVATION || '{}');
+    if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(o.tool) || typeof o.action !== 'string') throw new Error('invalid detached observation');
+    recordLearningObservation(binary, context, { tool: o.tool, action: o.action, session: String(o.session || '') }, { env: process.env, deadline: Date.now() + 14_000, allowed: () => learningContext().enabled });
+  } catch (error) { fail(error); }
 }
 
 const isMain = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
-if (isMain) {
+if (isMain && ['--observe', '--distill'].includes(process.argv[2])) {
+  runDetached(process.argv[2]);
+  process.exit(0);
+} else if (isMain) {
   try {
     if (learningContext().enabled) captureLearning(JSON.parse((await readStdinBounded({ maxBytes: 65536, emptyMs: 150 })).toString()));
   } catch { /* malformed input produces no persisted payload */ }

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,132 @@
+/**
+ * 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 { resolveRuflo } from './ruflo-bin.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+
+export const CURATED_PREFIX = 'project-state-current-';
+export const AUTO_PREFIX = 'project-state-auto-';
+const OWNER_NAMESPACES = ['default'];
+
+/**
+ * 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) };
+}
+
+/** 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' });
+    execFile(bin, ['memory', ...args, '--path', db], { 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) => 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;
+};
+const newest = (rows, prefix) => rows.filter((e) => e.key.startsWith(prefix))
+  .sort((a, b) => Number(b.createdAt ?? 0) - Number(a.createdAt ?? 0) || (a.key < b.key ? 1 : -1))[0] || 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 };
+}
+
+/** 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 };
+  const namespaces = [...new Set([store.namespace, ...OWNER_NAMESPACES])];
+  const [lists, lessons] = await Promise.all([Promise.all(namespaces.map((n) => listKeys(n, options))), listKeys('lessons', options, 20)]);
+  if (lists.every((rows) => rows === null)) {
+    return { status: 'unknown', context: '[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] ruflo memory list did not answer in time; nothing restored.' };
+  }
+  const tagged = lists.flatMap((rows, i) => (rows || []).map((e) => ({ ...e, namespace: e.namespace || namespaces[i] })));
+  const curated = newest(tagged, CURATED_PREFIX);
+  const auto = newest(tagged, AUTO_PREFIX);
+  const wanted = [curated, auto && (!curated || Number(auto.createdAt) > Number(curated.createdAt)) ? 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 (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) };
+}
+
+/**
+ * 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 options = { encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 8 * 1024 * 1024, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' } };
+  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 };
+}

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.