ruvnet-brain 4.5.7 → 4.5.8

package/plugin/scripts/learn-flush.mjs

@@ -1,201 +1,96 @@
 #!/usr/bin/env node
-// learn-flush.mjs — SessionEnd. Reads this session's learning queue (the workflow you just performed)
-// and feeds the distinct steps into the GLOBAL per-user SONA learner — ruflo hooks run with cwd=$HOME
-// so learnings accumulate in ONE store (~/.claude-flow), shared across ALL your projects. Project FACTS
-// never come here (the queue holds command verbs + file basenames, no content). Each installed RuvNet
-// Brain does this for its own user → everyone's brain gets recursively smarter about how THEY work. ADR-0017.
-//
-// Non-blocking, best-effort. Bounded (distinct actions, short timeouts). `--sync` waits (for tests);
-// the hook default backgrounds so SessionEnd never stalls.
-
+// SessionEnd schedules a finite detached learner; --sync is the explicit Console drain.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-import { readStdinBounded } from './hook-input.mjs';
-import { learningScope, loadRuntimePreferences } from './runtime-preferences.mjs';
-import { resolveRuflo, RUFLO_MISSING } from './ruflo-bin.mjs';
-import { projectDirectory } from './project-identity.mjs';
-
-// ONE BOUNDED LINE ON STDERR. stderr because a SessionEnd hook's stdout is not surfaced, and bounded
-// because a hook that prints a stack trace on every `/clear` gets muted — and a muted diagnostic is
-// no diagnostic at all (the same lesson as the session-start line that reported its own defect every
-// session for eight days and went unread).
-const warn = (msg) => { try { process.stderr.write(`learn-flush: ${msg}\n`); } catch { /* stderr gone */ } };
-
-const HOME = os.homedir();
-// RESIDUAL of #134/#104: RUVNET_BRAIN_PROJECT_DIR is never set by real hook dispatch on either host,
-// so it degraded back to raw cwd() in production. `projectDirectory()` (project-identity.mjs) is the
-// SAME CLAUDE_PROJECT_DIR-with-containment rule #85/#107 already fixed for the receipt/Console
-// agreement — reused here rather than trusting the variable unconditionally, which would reopen the
-// class of bug #107 was: an unrelated declared root overruling a cwd it does not actually contain.
-const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || projectDirectory({ env: process.env });
-// ISSUE #139 — this WRITER resolved scope correctly while two READERS hardcoded it, so they agreed
-// only by coincidence. The resolution moved into runtime-preferences.mjs and all three now call it;
-// a future scope is one edit, not three. Behaviour here is unchanged by design.
-const LEARNING_SCOPE = learningScope({ cwd: PROJECT });
-if (LEARNING_SCOPE === 'off') process.exit(0);
-
-// THE SESSION ID COMES OFF THE PAYLOAD, exactly as it does in learn-capture.sh (fixed 2026-07-27).
-//
-// This used to be `process.env.CLAUDE_SESSION_ID || 'default'`. Claude Code does not set that
-// variable, so every session on the machine read and rewrote ONE shared session-default.jsonl —
-// measured live at 147 lines, appended by several concurrent sessions. Both halves of this pipeline
-// have to agree about which file they mean, so both now read `session_id` from the payload the hook
-// is already handed, sanitise it the same way, and fall back the same way.
-//
-// The read is bounded: SessionEnd hands us a small JSON object and closes, but an unbounded
-// readFileSync(0) on a stdin that never closes is a hang with no upper bound. A payload we cannot
-// read in time simply yields no id, which lands on the same fallback as no payload at all.
-async function payloadSessionId() {
-  if (process.stdin.isTTY) return '';
-  try {
-    const raw = (await readStdinBounded()).toString('utf8');
-    const v = JSON.parse(raw)?.session_id;
-    return typeof v === 'string' ? v : '';
-  } catch { return ''; }
-}
-// A filename COMPONENT, never a path — the payload is untrusted input.
-const SID = ((await payloadSessionId()) || process.env.CLAUDE_SESSION_ID || '').replace(/[^A-Za-z0-9_-]/g, '') || 'default';
-const QUEUE_ROOT = LEARNING_SCOPE === 'user'
-  ? path.join(HOME, '.cache', 'ruvnet-brain', 'learn')
-  : path.join(PROJECT, '.swarm', 'ruvnet-brain-learn');
-const QUEUE = process.env.LEARN_QUEUE || path.join(QUEUE_ROOT, `session-${SID}.jsonl`);
-// Issue #105: this was a hardcoded `path.join(HOME, '.npm-global/bin/ruflo')` — the owner's npm
-// prefix. On any other prefix (Homebrew, nvm, Volta, plain `npm -g`) the path simply did not exist,
-// every feed below threw ENOENT, and every throw landed in a `catch {}` that said nothing. One
-// resolver, shared with distill-project.mjs and health-repair.mjs's original — see ruflo-bin.mjs.
-const RUFLO = resolveRuflo();
-const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
-const MAX_ACTIONS = 8; // bound the work so SessionEnd stays fast
-
-// THE DEADLINE. SessionEnd's registered timeout is 30s (plugin/hooks/hooks.json) and this hook fires
-// on EVERY session end — including every `/clear`. Measured on the owner's machine 2026-07-27, in all
-// four stdin regimes: 48–50s wall, killed at the cap every single time.
-//
-// The arithmetic was never survivable. MAX_ACTIONS is 8 and a real `ruflo hooks` call measured 3.83s,
-// so the feed queued ~31s of work into a 30s budget and was killed part-way through it. Worse, the
-// kill lands BEFORE the write-back that preserves the remainder, so the queue never shrinks and never
-// drains — a cap that guarantees the work it defers can never be done.
-//
-// A work limit has to be expressed in the currency the budget is denominated in. MAX_ACTIONS bounds
-// COUNT; this bounds TIME, and the two together mean the hook stops cleanly, keeps what it did not
-// feed, and exits well inside the cap. 20s leaves a full third of the budget for the write-back, the
-// process teardown, and a slow machine. Measured with a 4s-per-call stub and a 147-entry queue: 22.5s
-// wall at a 20s deadline (execFileSync's own kill handling costs a couple of seconds on top of the
-// budget), so the number is set at 18s to keep the real worst case around 20s — a third of the cap in
-// hand. The budget is the thing being bounded; the constant is chosen from the measurement, not from
-// how round it looks.
-const DEADLINE_MS = Number(process.env.LEARN_FLUSH_DEADLINE_MS) || 18_000;
-const DEADLINE = Date.now() + DEADLINE_MS;
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { learningContext } from './runtime-preferences.mjs';
+import { recordLearningObservation, distillLearning } from './learning-store.mjs';
+import { superviseLearning } from './learning-worker-supervisor.mjs';
+import { resolveRuflo } from './ruflo-bin.mjs';
+import { safeQueue, queueFiles, pendingRecords, acknowledge, safeAction, takeQueueLock,
+  ownsQueueLock, releaseQueueLock, WORKER_BUDGET_MS, writeExclusive, writeAtomic, readSafe } from './learning-queue.mjs';
 
-let lines = [];
-try { lines = fs.readFileSync(QUEUE, 'utf8').split('\n').filter(Boolean); } catch { process.exit(0); }
-if (!lines.length) process.exit(0);
-
-// Distinct workflow actions this session (dedupe → a session has only a handful of real patterns).
-//
-// COLLECT ALL, FEED SOME, KEEP THE REST (fixed 2026-07-22). This used to `break` at MAX_ACTIONS and
-// then delete the ENTIRE queue, so a session with 30 distinct actions fed 8 and destroyed 22 —
-// permanently, silently, while reporting success. Measured on the owner's machine the same day: the
-// queue stood at 491 raw captures, every one of which would have been discarded after feeding 8.
-//
-// The cap exists for a good reason (SessionEnd must stay fast) but a work LIMIT is not a licence to
-// destroy the work you didn't do. Now the remainder is written back and drains on the next flush,
-// so a deep queue converges instead of being truncated.
-const allDistinct = [];
-const seen = new Set();
-for (const line of lines) {
-  let s; try { s = JSON.parse(line); } catch { continue; }
-  const key = `${s.tool}|${(s.action || '').slice(0, 60)}`;
-  if (!s.action || seen.has(key)) continue;
-  seen.add(key);
-  allDistinct.push(s);
-}
-const actions = allDistinct.slice(0, MAX_ACTIONS);
-const deferred = allDistinct.slice(MAX_ACTIONS);
-
-// ruflo is genuinely not on this machine. SAY SO — once — and keep the queue. Exiting 0 keeps the
-// best-effort contract (an absent optional learner must never break SessionEnd); saying nothing at
-// all is what turned #105 into eight invisible ENOENTs and a queue that never drained.
-if (!RUFLO && actions.length) {
-  warn(`0/${actions.length} fed — ${RUFLO_MISSING}. The queue is KEPT for retry.`);
-  process.exit(0);
-}
+const started = Date.now();
+const budget = Math.min(WORKER_BUDGET_MS, Math.max(1, Number(process.env.LEARN_FLUSH_DEADLINE_MS) || WORKER_BUDGET_MS));
+const deadline = Math.min(started + budget, Number(process.env.RUVNET_LEARN_WORKER_EXPIRES) || Infinity);
+const context = () => learningContext();
+const initial = context();
+if (!initial.enabled) process.exit(0);
+const allowed = () => { const current = context(); return current.enabled && current.scope === initial.scope && current.queueDir === initial.queueDir; };
+let token = process.env.RUVNET_LEARN_WORKER_TOKEN;
+try { token ||= takeQueueLock(initial); } catch { process.exit(0); }
+if (!token || !ownsQueueLock(initial, token)) process.exit(0);
 
-let fed = 0;
-const failures = [];              // WHY each feed failed — the thing `catch {}` used to destroy
-let stoppedAt = actions.length;   // how far the feed actually got before the deadline
-for (let i = 0; i < actions.length; i++) {
-  const remaining = DEADLINE - Date.now();
-  // STOP CLEANLY, and stop BEFORE starting work that cannot finish inside the budget. A call begun
-  // at 19.9s with a 6s timeout would run to 25.9s, which is the whole failure in miniature — the
-  // budget has to bound the call, not just the decision to make it.
-  if (remaining <= 0) { stoppedAt = i; break; }
-  const s = actions[i];
-  const args = s.tool === 'Bash'
-    ? ['hooks', 'post-command', '-c', s.action, '-s', 'true']
-    : ['hooks', 'post-edit', '-f', s.action, '-s', 'true', '-o', 'session edit'];
-  try {
-    // One command, two real Ruflo scopes: project cwd keeps patterns local; HOME retains the
-    // cross-project SONA learner for users who explicitly chose `user`.
-    execFileSync(RUFLO, args, {
-      cwd: LEARNING_SCOPE === 'user' ? HOME : PROJECT,
-      env: RUFLO_ENV,
-      stdio: 'ignore',
-      timeout: Math.min(6000, remaining),
-    });
-    fed++;
-  } catch (e) {
-    // BEST-EFFORT, NOT SILENT. The old `catch { /* best-effort */ }` swallowed the reason, so a
-    // machine where every call failed looked exactly like one where every call worked: exit 0,
-    // no output, and the only trace a queue that never shrank. "Reports success while doing
-    // nothing" is the defect class this project treats as the worst thing it can ship. Keep going
-    // (one bad record must not stall session end), but keep the reason.
-    failures.push(String(e?.message || e).split('\n')[0].slice(0, 120));
+// No enumeration/sorting on the native hook's synchronous path.
+if (!process.argv.includes('--worker')) {
+  if (process.argv.includes('--sync') || process.argv.includes('--supervisor')) {
+    await superviseLearning(initial, token, deadline, { report: process.argv.includes('--sync') });
+  } else {
+    try {
+      const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--supervisor'], {
+        cwd: initial.projectDir, detached: true, stdio: 'ignore', windowsHide: true,
+        env: { ...process.env, RUVNET_LEARN_WORKER_TOKEN: token, RUVNET_LEARN_WORKER_EXPIRES: String(deadline), RUFLO_DAEMON_AUTOSTART: '0' },
+      });
+      child.once('error', () => releaseQueueLock(initial, token)); child.unref();
+    } catch { releaseQueueLock(initial, token); }
   }
-}
-// SURFACE IT. Distinct reasons only, at most two: eight copies of the same ENOENT is noise, and the
-// second distinct reason is usually where the real information is.
-if (failures.length) {
-  const distinct = [...new Set(failures)];
-  warn(`${failures.length}/${actions.length} feed call(s) FAILED via ${RUFLO}`
-    + ` — ${distinct.slice(0, 2).join(' | ')}${distinct.length > 2 ? ` (+${distinct.length - 2} more kind(s))` : ''}`
-    + (fed === 0 ? '. Nothing was learned; the queue is KEPT for retry.'
-      : `. ${fed} succeeded; the entire queue is KEPT for retry (successful actions may replay).`));
-  // Preserve the original bytes on ANY failed attempt. Rewriting only the deferred tail would
-  // discard failed actions whenever a sibling succeeded. This is at-least-once retry, not an
-  // exactly-once or concurrent-capture protocol; successful actions may be fed again.
   process.exit(0);
 }
-// Whatever the deadline cut off is WORK, not waste: it goes back on the front of the queue so the
-// next flush continues from there. Dropping it would turn a time limit into the same silent data
-// loss the count limit used to cause.
-if (stoppedAt < actions.length) deferred.unshift(...actions.slice(stoppedAt));
-
-// DERIVED, not asserted (F14, 2026-07-18): the queue is EVIDENCE, and it may only be destroyed when
-// its contents were actually fed. The old line deleted it unconditionally — a session where every
-// `ruflo hooks` call failed (fed=0) silently discarded the whole learning queue with nothing learned
-// and no trace. Now: nothing fed + something to feed ⇒ the queue survives for the next session-end
-// to retry. An empty queue (nothing to feed) is safe to remove.
-if (fed > 0 || allDistinct.length === 0) {
-  if (deferred.length) {
-    // Work remains. Write back ONLY what was not fed, so the next flush continues where this one
-    // stopped. Deleting here is what turned a rate limit into data loss.
-    try {
-      fs.writeFileSync(QUEUE, deferred.map((s) => JSON.stringify(s)).join('\n') + '\n');
-    } catch { /* if we cannot rewrite it, leaving the full queue is strictly safer than removing it */ }
-  } else {
-    try { fs.rmSync(QUEUE); } catch { /* leave it if we can't remove */ }
+const cursorFile = path.join(initial.queueDir, '.scan-cursor');
+let cursor = ''; try { cursor = readSafe(cursorFile, 256).toString(); } catch { /* first pass */ }
+let files; try { files = queueFiles(initial, { cursor, limit: 128, deadline }); } catch { if (!process.send) releaseQueueLock(initial, token); process.exit(0); }
+const result = { schemaVersion: 1, scope: initial.scope, startedAt: new Date().toISOString(),
+  fed: 0, acknowledged: 0, failed: 0, malformed: 0, scannedFiles: 0, exhausted: false, recorded: [], distillation: null,
+  contract: 'Exact CLI plus independent canonical AgentDB row commits observations; distillation and ratified lessons are separate; originals retained' };
+const binary = resolveRuflo({ home: initial.home });
+try {
+  let bytes = 0; let scanned = null;
+  for (const file of files.slice(0, 128)) {
+    if (Date.now() >= deadline || result.fed + result.failed >= 8 || bytes >= 16 * 1024 * 1024) break;
+    safeQueue(initial); result.scannedFiles++; scanned = path.basename(file);
+    let state;
+    try { state = pendingRecords(file); bytes += fs.statSync(file).size; }
+    catch { result.failed++; continue; } // Unsafe/torn sidecars remain intact; siblings still get a fair turn.
+    for (const record of state.records) {
+      if (Date.now() >= deadline || result.fed + result.failed >= 8) break;
+      if (!allowed() || !ownsQueueLock(initial, token)) break;
+      let row;
+      try { row = JSON.parse(record.raw); } catch { result.malformed++; continue; }
+      const action = safeAction(row.tool, row.action);
+      if (!record.key || !action) { result.malformed++; continue; }
+      if (!binary) { result.failed++; break; }
+      let delivery;
+      try {
+        delivery = recordLearningObservation(binary, initial, file, record, { tool: row.tool, action }, {
+          deadline, explicitLegacyApply: process.env.RUVNET_LEGACY_USER_APPLY === '1',
+          allowed: () => allowed() && ownsQueueLock(initial, token),
+        });
+      } catch { result.failed++; continue; }
+      result.recorded.push(delivery);
+      result.fed++;
+      if (!allowed() || !ownsQueueLock(initial, token)) break;
+      state.ack[record.key] = true;
+      acknowledge(file, state.ack); result.acknowledged++;
+    }
   }
-} else if (process.argv.includes('--sync')) {
-  console.log(`learn-flush: 0/${actions.length} fed (ruflo hooks failing?) — queue KEPT for retry next session-end`);
-}
-if (process.argv.includes('--sync')) {
-  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the ${LEARNING_SCOPE} learner`
-    // Say the deadline out loud when it fires. A budget that silently truncates reads as "that was
-    // all there was", which is the same lie as the count cap that preceded it.
-    + (stoppedAt < actions.length ? `; STOPPED at ${stoppedAt}/${actions.length} on the ${DEADLINE_MS}ms deadline` : '')
-    + (deferred.length ? `; ${deferred.length} distinct action(s) deferred to the next flush (queue kept, nothing discarded)` : ''));
+  if (binary && result.fed && allowed() && ownsQueueLock(initial, token) && deadline - Date.now() > 1000) {
+    try { result.distillation = distillLearning(binary, initial, { deadline, automatic: true, allowed: () => allowed() && ownsQueueLock(initial, token), explicitLegacyApply: process.env.RUVNET_LEGACY_USER_APPLY === '1' }); }
+    catch { result.distillation = { completed: false, reason: 'bounded canonical distillation unavailable', ratifiedLessons: 0 }; }
+  }
+  result.exhausted = Date.now() >= deadline || result.fed + result.failed >= 8;
+  if (allowed() && ownsQueueLock(initial, token)) {
+    if (scanned) writeAtomic(cursorFile, scanned);
+    const receipt = path.join(initial.queueDir, `.run-${Date.now()}-${process.pid}.json`);
+    writeExclusive(receipt, JSON.stringify({ ...result, endedAt: new Date().toISOString() }));
+  }
+} catch { result.failed++; }
+finally { if (!process.send) releaseQueueLock(initial, token); }
+if (process.argv.includes('--report')) console.log(`learn-flush: fed ${result.fed}; acknowledged ${result.acknowledged}; failed ${result.failed}; malformed ${result.malformed}; original queue is KEPT for retry/history`);
+
+// Keep the owned root alive until its supervisor terminates and confirms the whole tree.
+// A lost supervisor cannot keep this worker alive beyond its inherited deadline.
+if (process.send) {
+  process.send({ type: 'learning-worker-complete' });
+  await new Promise(resolve => setTimeout(resolve, Math.max(1, deadline - Date.now() + 600)));
 }
-process.exit(0);

package/plugin/scripts/learning-observation.mjs

@@ -0,0 +1,51 @@
+// Read-only evidence shared by Console and the training remedy. No queue or learner is initialized.
+import path from 'node:path';
+import fs from 'node:fs';
+import { learningTarget, learningStoreStatus } from './learning-store.mjs';
+import { queueFiles, pendingRecords, safeQueue, readSafe } from './learning-queue.mjs';
+import { learningContext } from './runtime-preferences.mjs';
+
+const queueContext = (queueDir) => path.basename(queueDir) === 'ruvnet-brain-learn'
+  ? { scope: 'project', queueDir, projectDir: path.dirname(path.dirname(queueDir)) }
+  : { scope: 'user', queueDir, home: path.dirname(path.dirname(path.dirname(queueDir))) };
+
+export function learningQueueFiles(queueDir) { return queueFiles(queueContext(queueDir)); }
+
+/** Pending evidence includes malformed/torn lines; acknowledged retained originals are history. */
+export function learningQueueDepth(queueDir) {
+  return learningQueueFiles(queueDir).reduce((depth, file) => depth + pendingRecords(file).records.length, 0);
+}
+
+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 { learningTarget(context, { env }); } catch { result.statusKnown = false; result.queueKnown = false; return result; }
+  try { result.queueDepth = learningQueueDepth(context.queueDir); }
+  catch { result.queueKnown = false; }
+  try { const lock = JSON.parse(readSafe(path.join(context.queueDir, '.worker-lock'), 4096)); result.workerRetirementUnconfirmed = lock.retirementUnconfirmed === true || (lock.retirementRequired === true && lock.expires < Date.now()); }
+  catch { /* Absent diagnostic lock grants no claim about a running process. */ }
+  try {
+    const latest = fs.readdirSync(safeQueue(context)).filter(n => /^\.run-\d+-\d+\.json$/.test(n))
+      .sort((a, b) => Number(b.split('-')[1]) - Number(a.split('-')[1]))[0];
+    const receipt = latest && JSON.parse(readSafe(path.join(context.queueDir, latest), 65536));
+    result.capturePendingFailure = result.queueDepth > 0 && ((Number.isSafeInteger(receipt?.failed) && receipt.failed > 0)
+      || (Number.isSafeInteger(receipt?.malformed) && receipt.malformed > 0));
+    result.distillationUnavailable = receipt?.distillation?.completed === false;
+  } catch { /* Unknown diagnostic is never fabricated success. */ }
+  if (context.scope === 'project') {
+    try { result.legacyUserDepth = learningQueueDepth(path.join(context.home, '.cache', 'ruvnet-brain', 'learn')); }
+    catch { result.legacyUserKnown = false; }
+  }
+  try {
+    result.learningDb = learningTarget(context, { env });
+    const state = learningStoreStatus(result.learningDb);
+    result.statusKnown = state.known;
+    result.trajectories = state.observations; // compatibility field; explicitly observations, never SONA trajectories.
+    result.observations = state.observations; result.patterns = state.patterns;
+    result.lastDistillAt = state.lastDistillAt;
+    if (state.lastDistillAt !== null) result.lastTrainSeconds = Math.max(0, (Date.now() - state.lastDistillAt) / 1000);
+  } catch { /* Missing consent/store/readback remains unknown. */ }
+  return result;
+}

package/plugin/scripts/learning-queue.mjs

@@ -0,0 +1,135 @@
+// Workflow queue transport only. Retained source bytes plus acknowledgments permit crash replay.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const MAX_QUEUE_BYTES = 1024 * 1024;
+export const WORKER_BUDGET_MS = 18_000;
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const nofollow = fs.constants.O_NOFOLLOW || 0;
+export const queueName = /^session-[A-Za-z0-9_-]+\.jsonl$/;
+
+/** Reject symlinks/junctions at every ancestor beneath the canonical selected scope. */
+export function safeQueue(context, create = false) {
+  const root = fs.realpathSync.native(context.scope === 'user' ? context.home : context.projectDir);
+  const relative = path.relative(root, context.queueDir);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('queue outside scope');
+  let current = root;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || fs.realpathSync.native(current) !== current) throw new Error('unsafe queue ancestor');
+  }
+  return current;
+}
+
+export function readSafe(file, maxBytes = MAX_QUEUE_BYTES) {
+  if (!fs.lstatSync(file).isFile()) throw new Error('unsafe queue file');
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | nofollow);
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > maxBytes) throw new Error('queue file exceeds bounded read');
+    return fs.readFileSync(fd);
+  } finally { fs.closeSync(fd); }
+}
+
+export function queueFiles(context, options = {}) {
+  try {
+    const dir = safeQueue(context);
+    if (Number.isInteger(options.limit)) {
+      const before = []; const after = []; let passed = !options.cursor;
+      const iterator = fs.opendirSync(dir);
+      try {
+        let entry;
+        while (Date.now() < options.deadline && (entry = iterator.readSync())) {
+          if (!queueName.test(entry.name)) continue;
+          const file = path.join(dir, entry.name);
+          if (!passed && entry.name === options.cursor) { passed = true; if (before.length < options.limit) before.push(file); continue; }
+          if (passed) { after.push(file); if (after.length >= options.limit) break; }
+          else if (before.length < options.limit) before.push(file);
+        }
+      } finally { iterator.closeSync(); }
+      return [...after, ...before].slice(0, options.limit);
+    }
+    return fs.readdirSync(dir).filter(name => queueName.test(name)).map(name => path.join(dir, name))
+      .sort((a, b) => fs.lstatSync(a).mtimeMs - fs.lstatSync(b).mtimeMs || a.localeCompare(b));
+  } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+
+/** Hash-bound offsets cannot acknowledge replaced source bytes or an appended sibling line. */
+export function pendingRecords(file) {
+  const bytes = readSafe(file); let ack = {};
+  try { ack = JSON.parse(readSafe(`${file}.ack.json`).toString()); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const records = []; let start = 0;
+  for (let end = 0; end < bytes.length; end++) {
+    if (bytes[end] !== 10) continue;
+    const line = bytes.subarray(start, end + 1); const key = `${start}:${hash(line)}`;
+    if (line.toString().trim() && ack[key] !== true) records.push({ key, raw: line.toString() });
+    start = end + 1;
+  }
+  // A torn final line is pending evidence; it can become complete on a legacy writer's next append.
+  if (start < bytes.length && bytes.subarray(start).toString().trim()) records.push({ key: null, raw: bytes.subarray(start).toString() });
+  return { records, ack };
+}
+
+export function writeExclusive(file, bytes) {
+  const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | nofollow, 0o600);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+export function writeAtomic(target, bytes) {
+  try { if (!fs.lstatSync(target).isFile()) throw new Error('unsafe acknowledgment'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temporary = `${target}.${randomUUID()}`;
+  writeExclusive(temporary, bytes);
+  fs.renameSync(temporary, target);
+}
+export function acknowledge(file, ack) { writeAtomic(`${file}.ack.json`, JSON.stringify(ack)); }
+
+/** Lease lasts longer than the finite worker. PID is diagnostic, never writer authority. */
+export function takeQueueLock(context, now = Date.now()) {
+  const dir = safeQueue(context); const file = path.join(dir, '.worker-lock');
+  const token = randomUUID(); const body = JSON.stringify({ token, expires: now + 60_000 });
+  try { writeExclusive(file, body); return token; } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const seen = readSafe(file).toString();
+  let expires;
+  try { const owner = JSON.parse(seen); if (owner.retirementUnconfirmed || owner.retirementRequired) return null; expires = owner.expires; } catch { expires = fs.lstatSync(file).mtimeMs + 60_000; }
+  if (!Number.isFinite(expires)) expires = fs.lstatSync(file).mtimeMs + 60_000;
+  if (!(expires < now)) return null;
+  const aside = `${file}.${token}`;
+  fs.renameSync(file, aside);
+  if (readSafe(aside).toString() !== seen) {
+    try { fs.linkSync(aside, file); } catch { /* another fenced owner already exists */ }
+    fs.rmSync(aside); return null;
+  }
+  fs.rmSync(aside);
+  try { writeExclusive(file, body); return token; } catch (error) { if (error.code === 'EEXIST') return null; throw error; }
+}
+
+export function ownsQueueLock(context, token) {
+  try {
+    safeQueue(context);
+    const lock = JSON.parse(readSafe(path.join(context.queueDir, '.worker-lock')).toString());
+    return !lock.retirementUnconfirmed && lock.token === token && Date.now() < lock.expires;
+  } catch { return false; }
+}
+export function releaseQueueLock(context, token) {
+  if (ownsQueueLock(context, token)) fs.rmSync(path.join(context.queueDir, '.worker-lock'));
+}
+
+// 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';
+}

package/plugin/scripts/learning-store.mjs

@@ -0,0 +1,105 @@
+// Canonical workflow observations; existing Ruflo is the sole writer, never the legacy JSON hook store.
+import fs from 'node:fs';
+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 { loadRuntimePreferences } from './runtime-preferences.mjs';
+import { loadNodeSqlite } from './node-sqlite.mjs';
+import { safeQueue, writeAtomic } from './learning-queue.mjs';
+
+export const LEARNING_NAMESPACE = 'learning-observations';
+export function learningTarget(context, { env = process.env, explicitLegacyApply = false } = {}) {
+  if (!context.enabled) throw new Error('learning consent disabled');
+  if (context.scope === 'project') return resolveProjectStore({ projectDir: context.projectDir, gitTimeoutMs: 1000 }).canonicalAgentDbPath;
+  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 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 });
+  if (resolved.projectRoot !== root) throw new Error('foreign global learner root');
+  return resolved.canonicalAgentDbPath;
+}
+
+export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000 } = {}) {
+  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') });
+  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 });
+  } finally { fs.rmSync(cwd, { force: true, recursive: true }); }
+}
+
+export function recordLearningObservation(binary, context, file, record, row, 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,
+    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 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 };
+}
+
+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;
+  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(); }
+}
+
+/** Existing $0 structural distiller, with a verified native WAL-safe snapshot before mutation. */
+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 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']);
+  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 };
+}