ruvnet-brain 4.6.3 → 4.7.0

package/plugin/scripts/hook-failures.mjs

@@ -0,0 +1,61 @@
+/**
+ * hook-failures.mjs — the reader half of "a failed advisory hook is a status line" (ADR-106).
+ *
+ * hook-shim.mjs appends one line to `<Brain home>/hook-failures.jsonl` whenever an advisory body
+ * exits nonzero, is killed, or cannot spawn (the writer is inlined there because the shim is
+ * boot-frozen). SessionStart calls failureLine() once: it summarizes failures recorded since the
+ * last summary and advances a byte cursor, so each failure is reported exactly once, never per fire.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const FAILURE_FILE = 'hook-failures.jsonl';
+export const FAILURE_LINE_PREFIX = '[RuvNet Brain — HOOK FAILURES]';
+const CURSOR_FILE = 'hook-failures.cursor';
+const MAX_READ = 256 * 1024;
+
+/** Summarize failures recorded after the cursor; advance it. Returns '' when there is nothing new. */
+export function failureLine(brainHome, { advance = true } = {}) {
+  const file = path.join(brainHome, FAILURE_FILE);
+  const cursorFile = path.join(brainHome, CURSOR_FILE);
+  let size;
+  try { size = fs.statSync(file).size; } catch { return ''; }
+  let offset = 0;
+  try { offset = Number(JSON.parse(fs.readFileSync(cursorFile, 'utf8')).offset) || 0; } catch { /* first read */ }
+  if (offset > size) offset = 0; // rotated by the writer
+  if (offset === size) return '';
+  const start = Math.max(offset, size - MAX_READ);
+  const buf = Buffer.alloc(size - start);
+  const fd = fs.openSync(file, 'r');
+  try { fs.readSync(fd, buf, 0, buf.length, start); } finally { fs.closeSync(fd); }
+  const rows = buf.toString('utf8').split('\n').flatMap((l) => { try { return l ? [JSON.parse(l)] : []; } catch { return []; } });
+  if (advance) { try { fs.writeFileSync(cursorFile, JSON.stringify({ offset: size })); } catch { /* re-reported next session */ } }
+  if (!rows.length) return '';
+  const byHook = new Map();
+  for (const r of rows) {
+    const id = String(r.hook || 'unknown').slice(0, 40);
+    const why = r.note ? String(r.note).split(':')[0].slice(0, 48) : r.error ? String(r.error).slice(0, 40) : r.signal ? String(r.signal) : `exit ${r.status}`;
+    const e = byHook.get(id) || { n: 0, why: new Set() };
+    e.n += 1; e.why.add(why); byHook.set(id, e);
+  }
+  const parts = [...byHook.entries()].sort((a, b) => b[1].n - a[1].n)
+    .map(([id, e]) => `${id} ×${e.n} (${[...e.why].slice(0, 3).join(', ')})`);
+  return `${FAILURE_LINE_PREFIX} ${rows.length} advisory hook run(s) did not complete or did not resolve since ${rows[0].at}: ${parts.join('; ')}. `
+    + `They failed open. Details: ${file}`;
+}
+
+/**
+ * The writer for bodies that run OUTSIDE the shim's watchdog (a refused `ruflo memory store`, a failed
+ * exact readback). Same file, same row shape as hook-shim.mjs's inlined recordFailure, so the next
+ * SessionStart's failureLine() reports it. Never throws: an unrecordable failure must not become a second one.
+ */
+export function recordHookFailure(fields, { brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain') } = {}) {
+  try {
+    const file = path.join(brainHome, FAILURE_FILE);
+    fs.mkdirSync(brainHome, { recursive: true });
+    try { if (fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`); } catch { /* absent */ }
+    fs.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), ...fields })}\n`, { mode: 0o600 });
+    return true;
+  } catch { return false; }
+}

package/plugin/scripts/hook-shim.mjs

@@ -122,7 +122,6 @@ const TABLE = {
   // invocation". Restored. wired-check.mjs's H6 fix does not depend on these keys existing either
   // way — it stopped trusting hook-shim.mjs as a blind generic spawner, not their presence here.
   'learn-capture':    { file: 'learn-capture.mjs',   interpreter: 'node', mode: 'advisory', offBehavior: 'silence', stdinBytes: 65536 },
-  'learn-flush':      { file: 'learn-flush.mjs',     interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   // 1 MiB, not 64 KiB: the Stop payload now carries `last_assistant_message`, and a long closing
   // message truncated mid-JSON would parse as `{}` and silently drop the whole capture.
   'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 1048576 },
@@ -268,7 +267,7 @@ function readHookInput(limit) {
  * even if an older one was already reported.
  *
  * WHY A TTL RATHER THAN A TRUE SESSION ID, stated plainly rather than implied: no session identifier
- * reaches this dispatcher. Claude Code does not set CLAUDE_SESSION_ID (learn-flush.mjs documents the
+ * reaches this dispatcher. Claude Code does not set CLAUDE_SESSION_ID (the learning hook documented the
  * same finding), and the only place `session_id` exists is the stdin payload — which the majority of
  * these table entries deliberately never read. So the window is an approximation of a session, not a
  * claim to be one: it bounds a persistent breakage to roughly one line per working session instead
@@ -312,6 +311,52 @@ function resolveCodeRoot() {
   } catch { return null; }
 }
 
+/**
+ * A FAILED ADVISORY BODY IS RECORDED, NEVER SILENT (ADR-106). Advisory bodies return 0 to the host
+ * whatever happened (below), and the host shows no stderr on exit 0 — so a crashed Stop gate used to
+ * leave no trace anywhere (measured 2026-10-11: a throwing continuation-gate body → shim exit 0,
+ * 0 bytes, nothing on disk). One bounded JSONL line per failure, read and summarized ONCE by
+ * SessionStart (hook-failures.mjs owns the reader and the file name; tests/unit/hook-failures.test.mjs
+ * holds the two copies of the name together, the same way brain-off.test.mjs holds the sentinel).
+ * Inlined, not imported, because this file is boot-frozen. Never throws, never prints.
+ */
+function recordFailure(fields) {
+  try {
+    const file = path.join(BRAIN_HOME, 'hook-failures.jsonl');
+    fs.mkdirSync(BRAIN_HOME, { recursive: true });
+    try { if (fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`); } catch { /* absent */ }
+    fs.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), hook: hookId, ...fields })}\n`, { mode: 0o600 });
+  } catch { /* an unrecordable failure must not become a second one */ }
+}
+
+/**
+ * THE WATCHDOG (ADR-106). The host kills a hook at its registered timeout and DISCARDS its output
+ * (measured: "UserPromptSubmit hook … timed out after 10s — output discarded"). So the shim stops the
+ * body itself 1.5 s before the registered timeout of THIS command (read from the frozen manifest it
+ * was registered from; under Codex the stable wrapper owns the kill instead), records one
+ * `timed-out-internally` line in the failure ledger, writes NOTHING partial, and exits 0. SessionStart
+ * then reports it once. stdout is captured and forwarded only when the body finished on its own.
+ */
+const WATCHDOG_MARGIN_MS = 1500;
+function registeredTimeoutMs(extraArgs) {
+  try {
+    // Under Codex the stable wrapper already owns a process-group kill below the host timeout
+    // (codex-hook-wrapper.mjs); a second, shorter watchdog here would pre-empt it and orphan the
+    // body's own children. So the watchdog is Claude's, where nothing else stands before the host.
+    if (process.env.RUVNET_CODEX_BUDGET_MS || process.env.RUVNET_HOOK_HOST === 'codex') return Infinity;
+    const manifest = JSON.parse(fs.readFileSync(path.join(PLUGIN_ROOT, 'hooks', 'hooks.json'), 'utf8'));
+    const want = ['hook-shim.mjs"', hookId, ...extraArgs].join(' ');
+    let best = Infinity;
+    for (const groups of Object.values(manifest.hooks || {})) {
+      for (const g of groups || []) for (const h of g.hooks || []) {
+        const c = String(h.command || '').replace(/\s+\|\|\s+true\s*$/, '');
+        if ((c.endsWith(want) || c.includes(`${want} `)) && Number.isFinite(h.timeout)) best = Math.min(best, h.timeout * 1000);
+      }
+    }
+    return best;
+  } catch { return Infinity; }
+}
+
 // Run one hook body. No shell is ever involved: spawnSync with an argument array, interpreter
 // chosen from the typed table — never from input.
 function runHook(file, activeVersion = '') {
@@ -345,11 +390,15 @@ function runHook(file, activeVersion = '') {
     ...(BRAIN_OFF && entry.offBehavior === 'partial' ? { RUVNET_BRAIN_OFF: '1' } : {}),
   };
   const io = hookInput !== null
-    ? { stdio: ['pipe', 'inherit', 'inherit'], input: hookInput }
-    : { stdio: 'inherit' };
+    ? { stdio: ['pipe', 'pipe', 'inherit'], input: hookInput }
+    : { stdio: ['inherit', 'pipe', 'inherit'] };
+  const registered = registeredTimeoutMs(extraArgs);
+  const watchdog = Number.isFinite(registered) ? Math.max(500, registered - WATCHDOG_MARGIN_MS) : undefined;
   let sessionTimeout;
   if (hookId === 'session-start') {
     try {
+      // The restore plans inside the watchdog, so it finishes cleanly instead of being killed mid-write.
+      if (watchdog) env.RUVNET_SESSION_START_DEADLINE_AT = String(Math.min(Number(env.RUVNET_SESSION_START_DEADLINE_AT) || Infinity, Date.now() + watchdog));
       const deadlineAt = sessionStartDeadlineAt({ host: env.RUVNET_HOOK_HOST || 'claude', env,
         startedAt: performance.timeOrigin, pluginRoot: path.resolve(path.dirname(file), '..') });
       env.RUVNET_SESSION_START_DEADLINE_AT = String(deadlineAt);
@@ -361,12 +410,28 @@ function runHook(file, activeVersion = '') {
     }
   }
   if (advisoryBudgetFor(hookId, extraArgs[0] || '') === null) recordContextBudget({ handler: hookId, event: extraArgs[0] || hookId, scope: 'unknown-unframed-context-unchanged' }, env);
-  const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env,
-    ...(sessionTimeout ? { timeout: sessionTimeout, killSignal: 'SIGKILL' } : {}) });
+  const limit = Math.min(sessionTimeout || Infinity, watchdog || Infinity);
+  const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env, maxBuffer: 16 * 1024 * 1024,
+    ...(Number.isFinite(limit) ? { timeout: limit, killSignal: 'SIGKILL' } : {}) });
+  const timedOut = r.error?.code === 'ETIMEDOUT' || (r.signal === 'SIGKILL' && Number.isFinite(limit));
+  if (timedOut) {
+    recordFailure({ event: extraArgs[0] || '', error: 'timed-out-internally', limitMs: limit, signal: r.signal || null });
+    return 0; // nothing partial reaches the host; a killed body never refuses
+  }
+  if (r.stdout?.length) {
+    // Synchronous, because process.exit() follows and an async pipe write could be cut off.
+    for (let off = 0, spins = 0; off < r.stdout.length && spins < 2000;) {
+      try { off += fs.writeSync(1, r.stdout, off); } catch (e) { if (e.code !== 'EAGAIN') break; spins += 1; Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5); }
+    }
+  }
   if (r.error) {
+    recordFailure({ event: extraArgs[0] || '', error: String(r.error.code || r.error.message).slice(0, 120), signal: r.signal || null });
     process.stderr.write(`[hook-shim] ${entry.file}: ${r.error.message}\n`);
     return entry.mode === 'blocking' ? 1 : 0;
   }
+  if (r.signal || (entry.mode !== 'blocking' && r.status !== 0)) {
+    recordFailure({ event: extraArgs[0] || '', status: r.status, signal: r.signal || null });
+  }
   // Blocking hooks: the exit code IS the contract — ground-before-write, design-wall, protect-state,
   // and hijack-ruvnet at an opted-in managedMemoryBoundary (ADR-063). Advisory hooks: always 0.
   //

package/plugin/scripts/learn-capture.mjs

@@ -1,44 +1,95 @@
 #!/usr/bin/env node
-// PostToolUse captures only a fixed workflow vocabulary, then schedules bounded orphan recovery.
-import path from 'node:path';
-import { randomUUID, createHash } from 'node:crypto';
+import fs from 'node:fs';
+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 } from './learning-queue.mjs';
+import { recordLearningObservation, distillObservations } from './learning-store.mjs';
+import { resolveRuflo } from './ruflo-bin.mjs';
+import { recordHookFailure } from './hook-failures.mjs';
 
-try {
-  const context = learningContext();
-  if (!context.enabled) process.exit(0);
-  const raw = await readStdinBounded({ maxBytes: 65536, emptyMs: 150 });
-  const input = JSON.parse(raw.toString());
-  if (input.hook_event_name && input.hook_event_name !== 'PostToolUse') process.exit(0);
-  const response = input.tool_response;
-  if (typeof response === 'string') {
-    const exit = /^Process exited with code (-?\d+)\s*$/m.exec(response);
-    if ((exit && Number(exit[1]) !== 0) || /Process running with session ID/.test(response)) process.exit(0);
+// 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 (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)) process.exit(0);
-  const tool = input.tool_name;
-  if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(tool)) process.exit(0);
-  const action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
-  if (!action) process.exit(0);
-  const fresh = learningContext();
-  if (!fresh.enabled || fresh.queueDir !== context.queueDir) process.exit(0);
-  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) process.exit(0);
-  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();
-} catch { /* advisory transport; unsafe/malformed input produces no persisted payload */ }
-process.exit(0);
+  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, 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, { 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;
+    if (input.hook_event_name && input.hook_event_name !== 'PostToolUse') return false;
+    const response = input.tool_response;
+    if (typeof response === 'string') {
+      const exit = /^Process exited with code (-?\d+)\s*$/m.exec(response);
+      if ((exit && Number(exit[1]) !== 0) || /Process running with session ID/.test(response)) return false;
+    }
+    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;
+    tool = input.tool_name;
+    if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(tool)) return false;
+    action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
+    if (!action) return false;
+    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 (error) {
+    if (tool && action) recordHookFailure({ hook: 'learn-capture', event: 'PostToolUse', error: String(error?.message || error).slice(0, 160) }, brainHome ? { brainHome } : undefined);
+    return false;
+  }
+}
+
+/** 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(); // 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 && ['--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 */ }
+  process.exit(0);
+}

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-'));
+}