ruvnet-brain 4.5.6 → 4.5.8

package/plugin/scripts/learn-capture.sh

@@ -1,242 +1,3 @@
 #!/bin/bash
-# learn-capture.sh — PostToolUse (Write|Edit|Bash). Appends ONE compact step to this session's learning
-# queue. A session is a trajectory (task -> steps -> outcome); learn-flush.mjs feeds the queue to the
-# GLOBAL SONA learner at SessionEnd, so "how you work" accumulates per-user across ALL projects — while
-# project FACTS stay in each project's .swarm/memory.db, never here. We record the workflow ACTION (a
-# command verb, a file's basename), never file CONTENT or secrets. ADR-0017.
-#
-# CONTRACT: PostToolUse is non-blocking — always exit 0, swallow every failure, no process spawn (fast).
-
-set -uo pipefail
-
-# One policy source for both capture and flush. `off` means zero bytes written. `project` keeps the
-# trajectory queue under this project's .swarm directory; `user` preserves the cross-project learner
-# introduced by ADR-0017. Tests and managed hosts may pass an already-resolved snapshot in
-# RUVNET_LEARNING_SCOPE so the two halves cannot disagree during one hook invocation.
-HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
-SCOPE="${RUVNET_LEARNING_SCOPE:-}"
-# CONFIGURED vs DEFAULTED, and this must be captured BEFORE the preferences fallback below.
-#
-# `project` is the DEFAULT scope, and `runtime-preferences.mjs --learning-scope` RESOLVES it —
-# measured 2026-08-19 against an empty config root, it returns "project", not "". So after the
-# fallback runs, an explicit opt-in and a bare default are indistinguishable. The first version of
-# this guard read SCOPE afterwards and was therefore always "configured", which let the
-# stranger-project mutation straight back in.
-#
-# The env var is the one signal that is unambiguously explicit: nothing sets it by default. A
-# project that opted in through the console instead is still covered by the `.swarm` clause below,
-# because adopting Ruflo's convention is itself the opt-in.
-SCOPE_CONFIGURED=0
-[ -n "$SCOPE" ] && SCOPE_CONFIGURED=1
-if [ -z "$SCOPE" ] && [ -f "$HERE/runtime-preferences.mjs" ] && command -v node >/dev/null 2>&1; then
-  SCOPE=$(node "$HERE/runtime-preferences.mjs" --learning-scope 2>/dev/null) || SCOPE=""
-fi
-case "$SCOPE" in
-  off) exit 0 ;;
-  user|project) ;;
-  *) SCOPE="project" ;;
-esac
-
-# BOUNDED READ. An unqualified `read` waits forever on a stdin that is opened and never closed, and
-# an unbounded accumulator turns a large payload into an unbounded regex scan. Claude Code always
-# writes the payload and closes, so neither costs a normal turn — which is exactly why a hook that
-# CAN hang survives: the only thing ending it is a timeout owned by someone else. -t 2 is ~40x a real
-# payload's delivery time; the size cap is ~30x the largest real payload. The trailing `[ -n "$_l" ]`
-# keeps the final unterminated line, which is what the original `||` clause was for.
-INPUT=""
-_l=""   # set -u: a read that times out before any byte leaves _l unset ("unbound variable" on stderr)
-while IFS= read -r -t 2 _l; do
-  INPUT+="$_l"
-  [ ${#INPUT} -ge 65536 ] && break
-done
-# Truncate the ASSEMBLED string, not just each iteration: a hook payload is one line with no trailing
-# newline, so `read` hands back the whole thing at once in $_l and the in-loop cap never fires.
-[ -n "$_l" ] && INPUT+="$_l"
-INPUT="${INPUT:0:65536}"
-[ -n "$INPUT" ] || exit 0
-
-TOOL=""
-re_t='"tool_name"[[:space:]]*:[[:space:]]*"([^"]*)"'
-[[ $INPUT =~ $re_t ]] && TOOL="${BASH_REMATCH[1]}"
-[ -n "$TOOL" ] || exit 0
-
-ACTION=""
-case "$TOOL" in
-  Bash)
-    # Capture the VERB CHAIN ONLY — "git push", "npm test", "npx vercel" — never the arguments.
-    #
-    # This previously took the first 120 chars up to an embedded quote and called that "verb, not
-    # facts". It wasn't. Unquoted inline secrets were captured in full and written to disk, proven
-    # by test: `export AWS_SECRET_ACCESS_KEY=wJalr... && psql postgres://admin:Hunter2Pass@db/prod`
-    # landed verbatim in session-*.jsonl, and from there fed the global learner. Real command lines
-    # routinely carry API keys, DB URLs with inline passwords, and internal hostnames — on a
-    # corporate laptop the hostnames alone are a DLP finding.
-    #
-    # Now: keep at most the first two tokens, and stop at the first token that carries DATA rather
-    # than INTENT (contains = / @ : , is a flag, or is improbably long). "export FOO=secret" records
-    # "export"; "cd /Users/me/ClientProject" records "cd". The learner only ever needed the verb.
-    # THE CAPTURE WAS MANGLED, and the mangling was invisible (fixed 2026-07-27).
-    #
-    # `"command"…"([^"]*)"` cannot cross a JSON-escaped quote — the exact bug hook-input.mjs exists to
-    # end — so `cd "/tmp/some dir"` captured the two bytes `cd \`, and that trailing backslash then
-    # broke the JSON line it was printed into. Measured on the owner's live queue:
-    #
-    #     {"tool":"Bash","action":"cd \"}      ← JSON.parse: Unterminated string at position 31
-    #
-    # learn-flush drops every unparseable line with a bare `continue`, so the capture reported success,
-    # the queue grew, and the learner received nothing. A pipe severed in the middle while both ends
-    # report health is this project's signature failure mode.
-    #
-    # The fix is to stop at the first quote OR backslash and take a PREFIX — no closing-quote anchor,
-    # because the first two tokens are all this hook ever wanted. A command that opens with a quoted
-    # path yields an empty prefix and is simply not captured, which is strictly better than writing a
-    # line that cannot be read back.
-    re_c='"command"[[:space:]]*:[[:space:]]*"([^"\]*)'
-    if [[ $INPUT =~ $re_c ]]; then
-      set -f                      # no globbing while we word-split untrusted text
-      _n=0
-      for _tok in ${BASH_REMATCH[1]}; do
-        case "$_tok" in
-          *=*|*/*|*@*|*:*|-*) break ;;
-        esac
-        [ ${#_tok} -gt 24 ] && break
-        ACTION="${ACTION:+$ACTION }$_tok"
-        _n=$((_n + 1))
-        [ "$_n" -ge 2 ] && break
-      done
-      set +f
-    fi
-    ;;
-  Write|Edit|MultiEdit)
-    re_f='"file_path"[[:space:]]*:[[:space:]]*"([^"]*)"'
-    [[ $INPUT =~ $re_f ]] && ACTION="edit ${BASH_REMATCH[1]##*/}"   # basename only — no full path
-    ;;
-esac
-[ -n "$ACTION" ] || exit 0
-
-# THE SESSION ID IS IN THE PAYLOAD WE ALREADY READ — and it was being thrown away.
-#
-# This read `${CLAUDE_SESSION_ID:-default}`, an env var Claude Code does not set, so EVERY session on
-# a machine appended to one shared `session-default.jsonl`. Measured on the owner's machine
-# 2026-07-27: one file, 147 lines deep, written concurrently by several live sessions — the same
-# many-writers-one-path shape as ADR-050, and it makes "this session's trajectory" a fiction, because
-# the queue is a blend of every session that happened to be open.
-#
-# `session_id` is a field on the very payload this hook already parsed. Prefer it; fall back to the
-# env var; then to 'default'. SANITISED before it becomes a filename component: the payload is
-# untrusted input, and `session_id` reaching an unfiltered path join is a traversal waiting to happen.
-SID=""
-re_s='"session_id"[[:space:]]*:[[:space:]]*"([^"\]*)"'
-[[ $INPUT =~ $re_s ]] && SID="${BASH_REMATCH[1]}"
-[ -n "$SID" ] || SID="${CLAUDE_SESSION_ID:-}"
-# Dots are dropped along with everything else outside this set: real session ids are uuids, and
-# keeping `.` would let a crafted id survive as `..`-shaped debris in a filename for no benefit.
-SID="${SID//[^A-Za-z0-9_-]/}"           # a filename COMPONENT, never a path
-[ -n "$SID" ] || SID="default"
-if [ "$SCOPE" = "user" ]; then
-  DIR="$HOME/.cache/ruvnet-brain/learn"
-else
-  # ISSUE #134 — THE SAME PROJECT ROOT THE READER COMPUTES, BY THE SAME RULE.
-  #
-  # This was bare `$PWD` while learn-flush.mjs:26 and health-repair.mjs:32 both resolve
-  # `RUVNET_BRAIN_PROJECT_DIR || cwd`. This hook is wired on PostToolUse, so it runs after EVERY tool
-  # call — and any command that leaves the shell below the project root (a test run, a build, any
-  # tooling that cd's) made the WRITER create a queue in a directory the READER never looks in. Those
-  # events are not misfiled, they are orphaned: nothing ever drains them.
-  #
-  # This is issue #104's residual. #104 fixed the two halves of the FLUSH to agree about which project
-  # they mean; the component that actually creates the queue was not brought along, so the invariant
-  # held for two of three participants and was violated by the one doing the writing. Same shape as
-  # ADR-066: a writer and a reader that disagree about the store make the recording theatre.
-  # RESIDUAL of #134/#104: RUVNET_BRAIN_PROJECT_DIR is never set by real hook dispatch on either
-  # host (neither hook-shim.mjs nor codex-hook-adapter.mjs seeds it), so it degraded back to bare
-  # $PWD in production. CLAUDE_PROJECT_DIR is the one project-root signal both hosts DO provide on
-  # every invocation. Trusted only when $PWD actually lies inside it — the SAME containment rule
-  # project-identity.mjs's projectDirectory() applies for the identical reason (#85/#107: an
-  # unrelated declared root must never overrule a cwd it does not contain). A plain string-prefix
-  # check, not a realpath/inode compare, to honour this hook's own no-process-spawn contract.
-  ROOT_DIR="$PWD"
-  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
-    CPD="${CLAUDE_PROJECT_DIR%/}"
-    # Git Bash presents PWD as /c/... while Node supplies CLAUDE_PROJECT_DIR as C:\\... on
-    # Windows. Compare normalized, case-folded spellings so the real project-root signal works
-    # on both hosts without spawning a platform-specific path converter.
-    _pwd_for_compare="$PWD"
-    if [ -n "$(pwd -W 2>/dev/null || true)" ]; then _pwd_for_compare="$(pwd -W)"; fi
-    _pwd_cmp=$(printf '%s' "$_pwd_for_compare" | tr '\\\\' '/' | tr '[:upper:]' '[:lower:]')
-    _cpd_cmp=$(printf '%s' "$CPD" | tr '\\\\' '/' | tr '[:upper:]' '[:lower:]')
-    case "$_pwd_cmp/" in "$_cpd_cmp"/*) ROOT_DIR="$CPD" ;; esac
-  fi
-  DIR="${RUVNET_BRAIN_PROJECT_DIR:-$ROOT_DIR}/.swarm/ruvnet-brain-learn"
-fi
-# PROJECT SCOPE MEANS THE PROJECT MUST HAVE OPTED IN. In project scope $DIR sits under `.swarm`,
-# which is Ruflo's own convention and is created by `ruflo init` — so its PRESENCE is the project's
-# opt-in and its ABSENCE is a project that has not adopted the brain. This hook runs machine-wide on
-# every PostToolUse, so an unconditional mkdir planted `.swarm/` in EVERY repository the user opened.
-# Measured 2026-08-14 by the both-hosts conformance gate in a temp project with no git and no brain
-# artifacts; ADR-058 D5 — never touch what we do not own. User scope is unaffected: that queue lives
-# under the brain's OWN cache directory, which we do own and may create.
-# CREATE THE QUEUE ONLY WHERE THE PROJECT ACTUALLY OPTED IN.
-#
-# First attempt required an existing `.swarm`, which stopped the stranger-project mutation but ALSO
-# broke a legitimate first run: a project that explicitly sets RUVNET_LEARNING_SCOPE=project before
-# it has ever captured anything got nothing, and `learning-scope-policy` went red. Presence of
-# `.swarm` was the wrong discriminator — it answers "has Ruflo run here", not "did this project ask
-# for learning".
-#
-# The right one is whether the scope was CONFIGURED (env or runtime-preferences) rather than
-# inherited from the default. A stranger's repo sets neither, so nothing is created there; a project
-# that opted in gets its queue on the very first capture, `.swarm` or not. An existing `.swarm` is
-# still honoured on its own, because a repo already carrying Ruflo's convention has plainly adopted it.
-case "$DIR" in
-  */.swarm/*)
-    if [ "$SCOPE_CONFIGURED" != "1" ] && [ ! -d "$(dirname "$DIR")" ]; then exit 0; fi
-    ;;
-esac
-# Owner-only (0700 dir / 0600 file). This queue was 0644 inside a 0755 dir: on macOS every local
-# account is normally in `staff`, so any other user on a shared or corporate machine could read it.
-( umask 077 && mkdir -p "$DIR" ) 2>/dev/null || exit 0
-QUEUE="$DIR/session-$SID.jsonl"
-[ -e "$QUEUE" ] || { : > "$QUEUE" 2>/dev/null && chmod 600 "$QUEUE" 2>/dev/null; } || true
-printf '{"tool":"%s","action":"%s"}\n' "$TOOL" "${ACTION//\"/\\\"}" >> "$QUEUE" 2>/dev/null || true
-
-# ── HEARTBEAT FLUSH (ADR-027) ────────────────────────────────────────────────────────────────────
-# The flush used to fire ONLY on a clean SessionEnd. Sessions compact, crash, get resumed, or are
-# killed — none of those reach SessionEnd — so the queue silently grew to 1,884 undelivered events
-# over days while the learner sat at 5 trajectories, last trained six days earlier. Draining it took
-# the learner to 412/412 in one command. A queue that only empties on a graceful exit will always
-# leak; activity itself must be the trigger.
-#
-# So: every HEARTBEAT_EVERY captures, drain in the BACKGROUND. Detached and fully silent — this runs
-# inside a PostToolUse hook and must never add latency to the user's turn or fail one. Cheap check
-# (a line count) on the common path; real work only at the threshold.
-# LEVEL-TRIGGERED, NOT EDGE-TRIGGERED. This is the whole fix, and the bug it replaces was severe.
-#
-# The condition used to be `LINES >= 200 && LINES % 200 == 0` — it fired ONLY when the count landed
-# exactly on a multiple of 200. Two captures arriving between checks, or any concurrent write,
-# steps the counter over the window and the flush NEVER fires again. Measured on the owner's machine
-# 2026-07-22: the queue was at 491. It had sailed past both 200 and 400 without draining once, and
-# would have grown forever.
-#
-# The failure mode is the nastiest kind: capture works, the learner works, and the PIPE BETWEEN THEM
-# is severed — while every surface honestly reports both ends as healthy. "Is learning on?" had no
-# true answer, because learning is not a switch; it is a chain, and one link was open.
-#
-# `-ge` cannot skip a window. It fires on every capture past the threshold until the queue is
-# actually drained, which is the definition of level-triggered: the condition is the QUEUE'S DEPTH,
-# not the instant it crossed a line.
-HEARTBEAT_EVERY=200
-LINES=$(wc -l < "$DIR/session-$SID.jsonl" 2>/dev/null || echo 0)
-if [ "$LINES" -ge "$HEARTBEAT_EVERY" ]; then
-  # Debounce so a deep queue doesn't spawn a flush on EVERY subsequent capture: at most one drain
-  # per minute. Without this, level-triggering trades a stuck queue for a fork storm.
-  STAMP="$DIR/.last-flush"
-  NOW=$(date +%s)
-  LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
-  if [ $((NOW - LAST)) -ge 60 ]; then
-    echo "$NOW" > "$STAMP" 2>/dev/null || true
-    FLUSH="$HERE/learn-flush.mjs"
-    [ -f "$FLUSH" ] && (RUVNET_LEARNING_SCOPE="$SCOPE" nohup node "$FLUSH" >/dev/null 2>&1 &) || true
-  fi
-fi
-exit 0
+# Compatibility entry; native registrations use the bounded Node body on both hosts.
+exec node "$(dirname "$0")/learn-capture.mjs"

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