ruvnet-brain 4.6.4 → 4.7.1

package/plugin/scripts/decision-gate.mjs

@@ -162,6 +162,7 @@ const POLICY = (id, file, interpreter = 'bash') => ({ id, file, interpreter });
 const REFUSAL_POLICIES = [
   POLICY('protect-state', 'protect-brain-state.sh'),
   POLICY('hijack-ruvnet', 'hijack-ruvnet.sh'),
+  POLICY('substitution-wall', 'substitution-wall.mjs', 'node'), // owner ruling 2026-10-12: only CALL rUv's memory tools; refuses a rebuilt transport (outbox/queue/journal/replay), in this repo only
   POLICY('ground-before-write', 'ground-before-write.sh'), POLICY('decision-recall', 'decision-recall-gate.mjs', 'node'), // ADR-106
   // adr-currency-gate fires on the EDIT, where the pre-push gate fires on the push. Same rule, same
   // machinery (it calls doc-currency.mjs, never a second copy of the logic) — moved to the earliest
@@ -181,7 +182,7 @@ const SPEECH = { id: 'unprompted-speech', file: 'unprompted-runtime.mjs', interp
 
 /** Which policies apply to which PreToolUse sub-event, mirroring the matchers they replaced. */
 const REGISTRY = {
-  'write': ['protect-state', 'hijack-ruvnet', 'ground-before-write', 'decision-recall', 'adr-currency', 'duplicate-code'],
+  'write': ['protect-state', 'hijack-ruvnet', 'substitution-wall', 'ground-before-write', 'decision-recall', 'adr-currency', 'duplicate-code'],
 };
 
 export function policiesFor(event, registry = REGISTRY, all = REFUSAL_POLICIES) {
@@ -287,7 +288,6 @@ function payloadInput(payload) { return parsed(payload).tool_input || {}; }
  * `Cannot access 'speechEventFor' before initialization` on this gate's first live refusal.
  */
 function speechEventFor(event) { return event === 'bash' ? 'PreToolUse-bash' : 'PreToolUse-write'; }
-
 // ── Runtime ──────────────────────────────────────────────────────────────────────────────────────
 if (isMain()) {
   const started = Date.now();

package/plugin/scripts/decision-record.mjs

@@ -6,7 +6,6 @@
  *   node decision-record.mjs --consult "<topic>"            consequential recall + persisted receipt
  *   node decision-record.mjs --record --what W --why Y --shape S --evidence kind:ref [...]
  *                            [--supersedes <key>]... [--status ratified|detected-unconfirmed]
- *   node decision-record.mjs --flush                        retry records left pending by a refusal
  *
  * Two hooks consume the facts this file produces (ADR-106): decision-gate's `decision-recall` policy
  * reads the consult receipt before a new ADR or an ADR status change; continuation-gate reads the
@@ -15,7 +14,8 @@
  * Store contract (ADR-105 §3, `ruflo memory store --help` read 2026-10-11): every write is
  * `--no-upsert --require-native --append-only --path <abs>` from a private scratch cwd with no
  * CLAUDE_FLOW_MEMORY_PATH; a row is committed only when an exact-key readback returns the same
- * bytes; any other refusal stays pending on disk (mode 0600, fsynced) and is never reported as done.
+ * bytes; any other refusal is LOUD — a hook-failures row plus the printed reason — and is never reported as
+ * done. Nothing is kept on disk for a later replay (owner ruling 2026-10-12: no private outbox).
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -28,8 +28,9 @@ import { maskExcludedPaths } from './turn-capture-privacy.mjs';
 import { resolveTurnDb, readSettledTranscript } from './turn-outcome-capture.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
-import { rufloRunDir } from './project-progression-store.mjs';
+import { rufloRunDir } from './ruflo-bin.mjs';
 import { currentTurnRecords } from './completion-claim-evidence.mjs';
+import { recordHookFailure } from './hook-failures.mjs';
 
 export const DECISION_SCHEMA = 'ruvnet-brain.decision-record';
 export const STATUSES = Object.freeze(['ratified', 'detected-unconfirmed']);
@@ -151,21 +152,11 @@ export function defaultReadBack({ ruflo, db, namespace, key }) {
   return { content: r.status === 0 ? r.stdout.trim() : null };
 }
 
-const pendingDir = (db) => path.join(path.dirname(db), '.decision-records-pending');
-function writePending(db, entry) {
-  const dir = pendingDir(db);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const file = path.join(dir, `${entry.key}.json`);
-  const fd = fs.openSync(file, 'w', 0o600);
-  try { fs.writeSync(fd, JSON.stringify(entry)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
-  return file;
-}
-
 /**
- * The §3 door. committed | already-stored | quarantined | pending — never "committed" without an
+ * The §3 door. committed | already-stored | quarantined | refused — never "committed" without an
  * exact readback of the same bytes, and a refusal is never treated as a duplicate.
  */
-export function storeDecision({ ruflo, db, namespace, key, value, store = defaultStore, readBack = defaultReadBack, keepPending = true }) {
+export function storeDecision({ ruflo, db, namespace, key, value, store = defaultStore, readBack = defaultReadBack }) {
   const prior = readBack({ ruflo, db, namespace, key });
   if (typeof prior.content === 'string' && prior.content === value) return { state: 'already-stored', key };
   if (typeof prior.content === 'string' && prior.content && prior.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
@@ -174,23 +165,8 @@ export function storeDecision({ ruflo, db, namespace, key, value, store = defaul
   if (result.status === 0 && back.content === value) return { state: 'committed', key };
   if (typeof back.content === 'string' && back.content && back.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
   const reason = redactText(String(result.output || '').trim().split('\n').filter(Boolean).slice(-1)[0] || `store exited ${result.status}`).slice(0, 300);
-  const pending = keepPending ? writePending(db, { key, namespace, value, at: new Date().toISOString(), reason }) : null;
-  return { state: 'pending', key, reason, pending };
-}
-
-/** Replay pending records through the same door; a committed one leaves the pending directory. */
-export function flushPending({ ruflo, db, store = defaultStore, readBack = defaultReadBack }) {
-  const out = [];
-  let names = [];
-  try { names = fs.readdirSync(pendingDir(db)).filter((n) => n.endsWith('.json')); } catch { return out; }
-  for (const name of names) {
-    const file = path.join(pendingDir(db), name);
-    let entry; try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { out.push({ state: 'unreadable', file }); continue; }
-    const r = storeDecision({ ruflo, db, namespace: entry.namespace, key: entry.key, value: entry.value, store, readBack, keepPending: false });
-    if (r.state === 'committed' || r.state === 'already-stored') fs.rmSync(file, { force: true });
-    out.push(r);
-  }
-  return out;
+  recordHookFailure({ hook: 'decision-record', event: 'record', error: `not recorded: ${reason}`.slice(0, 160) });
+  return { state: 'refused', key, reason };
 }
 
 // ── consult receipt (read before deciding) ─────────────────────────────────────────────────────
@@ -267,7 +243,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const next = () => { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); return v; };
-    if (['--consult', '--record', '--flush'].includes(a)) { o.mode = a.slice(2); if (a === '--consult') o.topic = next(); }
+    if (['--consult', '--record'].includes(a)) { o.mode = a.slice(2); if (a === '--consult') o.topic = next(); }
     else if (a === '--what') o.what = next();
     else if (a === '--why') o.why = next();
     else if (a === '--shape') o.shape = next();
@@ -286,7 +262,7 @@ function parseArgs(argv) {
 export async function main(argv = process.argv.slice(2), { env = process.env, out = process.stdout, err = process.stderr, recallFn, store, readBack } = {}) {
   let o;
   try { o = parseArgs(argv); } catch (e) { err.write(`decision-record: ${e.message}\n`); return 2; }
-  if (!o.mode) { err.write('decision-record: one of --consult "<topic>", --record, --flush is required\n'); return 2; }
+  if (!o.mode) { err.write('decision-record: one of --consult "<topic>", --record is required\n'); return 2; }
   const projectDir = path.resolve(o.project || process.cwd());
   const brainHome = brainHomeOf(env);
   let target;
@@ -306,11 +282,6 @@ export async function main(argv = process.argv.slice(2), { env = process.env, ou
   const ruflo = resolveRuflo({ env });
   if (!ruflo) { err.write('decision-record: not recorded — global ruflo not found\n'); return 3; }
   try { if (!fs.statSync(target.db).isFile()) throw new Error(); } catch { err.write('decision-record: not recorded — project has no canonical store (.swarm/memory.db)\n'); return 3; }
-  if (o.mode === 'flush') {
-    const rows = flushPending({ ruflo, db: target.db });
-    out.write(`decision-record flush: ${rows.map((r) => `${r.key || r.file} ${r.state}`).join('; ') || 'nothing pending'}\n`);
-    return rows.every((r) => ['committed', 'already-stored'].includes(r.state)) ? 0 : 3;
-  }
   const identity = resolveProjectStore({ projectDir, gitTimeoutMs: 1000 }).projectIdentity.id;
   const built = buildDecisionRecord(o, { projectRoot: target.projectRoot, projectIdentity: identity,
     host: env.RUVNET_HOOK_HOST === 'codex' ? 'codex' : env.CLAUDE_PLUGIN_ROOT || env.CLAUDECODE ? 'claude' : 'cli',
@@ -329,7 +300,7 @@ export async function main(argv = process.argv.slice(2), { env = process.env, ou
     out.write(`decision-record: supersedes ${key} — ${String(row.what).slice(0, 120)}\n`);
   }
   const r = storeDecision({ ruflo, db: target.db, namespace, key: built.key, value: built.value, ...(store ? { store } : {}), ...(readBack ? { readBack } : {}) });
-  out.write(`decision-record: ${r.state} ${r.key} (namespace ${namespace})${r.reason ? ` — ${r.reason}` : ''}${r.pending ? ` — retained for --flush` : ''}\n`);
+  out.write(`decision-record: ${r.state} ${r.key} (namespace ${namespace})${r.reason ? ` — ${r.reason}` : ''}${r.state === 'refused' ? ` — NOT recorded (logged to hook-failures). A store that committed but did not read back may still hold it: run \`ruflo memory retrieve -k ${r.key} -n ${namespace} --path ${target.db}\` before re-running --record` : ''}\n`);
   if (!['committed', 'already-stored'].includes(r.state)) return 3;
   let ok = true;
   for (const oldKey of built.record.supersedes) {

package/plugin/scripts/grok-hook-adapter.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * grok-hook-adapter.mjs — the Grok CLI host boundary. Grok payloads in, the shared Brain hook bodies
+ * (through hook-shim.mjs, unchanged) in the middle, Grok-valid output back. Registered only by
+ * plugin/hooks/grok-hooks.json, which Grok selects through plugin/.grok-plugin/plugin.json.
+ *
+ * Every rule below is either quoted from Grok's shipped docs (~/.grok/docs/user-guide/10-hooks.md,
+ * grok 1.0.50) or was measured on a real `grok -p` turn on 2026-10-13
+ * (tests/fixtures/hook-payloads/grok-1.0.50/). Where the docs are silent the behaviour is marked
+ * UNVERIFIED in grok-hooks.json and the contract test, never guessed here.
+ *
+ *   · INPUT. Grok sends camelCase keys plus snake_case copies of SOME of them (measured: session_id,
+ *     tool_name, tool_input, tool_response, transcript_path; NOT stop_hook_active,
+ *     last_assistant_message or prompt_id). hook-input.mjs normalizeHostEvent() already owns that
+ *     mapping (and Grok's tool names: search_replace -> Edit, run_terminal_command -> Bash); it is
+ *     reused here, not restated. prompt_id is added from promptId.
+ *   · TRANSCRIPT. Grok's transcriptPath is its own ACP update log (…/updates.jsonl), not Claude's
+ *     transcript. Every body that parses a transcript parses Claude's format only, so the path is
+ *     withheld: the bodies then report their transcript half UNKNOWN (as on Codex) instead of
+ *     misreading a foreign file.
+ *   · SESSION-END STOP. "A separate Stop also fires at session end (reason: "channel_closed" or
+ *     "shutdown"); its decision output is parsed but ignored" (10-hooks.md:399). Measured: a Stop with
+ *     reason "shutdown" arrived after SessionEnd. It is not a turn, so no body runs for it.
+ *   · OUTPUT. PreToolUse: exit 2 is a deny and the first stderr line its reason (10-hooks.md:377);
+ *     JSON permissionDecision/additionalContext use Claude's vocabulary (:318-321). PostToolUse:
+ *     stdout is parsed (:341); prose is wrapped as additionalContext rather than recorded as malformed.
+ *     Stop: Claude's decision/reason/additionalContext vocabulary "works unchanged" (:497); non-JSON is
+ *     an allow (:391). SessionStart, UserPromptSubmit, PreCompact, SessionEnd: stdout is ignored or
+ *     discarded (:113, :531), so none is written.
+ *   · FAIL OPEN. Only decision-gate may refuse. Any other non-zero status, a timeout or a crash exits 0,
+ *     and a kill by this adapter's own budget is one hook-failures row (same writer as the Codex wrapper).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { normalizeHostEvent } from './hook-input.mjs';
+import { developmentHooksSuspended } from './development-maintenance.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(HERE, '..');
+
+/** Ids whose exit 2 is a refusal Grok must see. Must name only ids hook-shim.mjs calls 'blocking'. */
+export const GROK_BLOCKING_HOOKS = Object.freeze(new Set(['decision-gate']));
+
+/** Events whose stdout Grok reads (10-hooks.md:531). Everything else is written nowhere. */
+export const GROK_OUTPUT_EVENTS = Object.freeze(new Set(['PreToolUse', 'PostToolUse', 'Stop']));
+
+/**
+ * This adapter's own kill budget, below the registration timeout in grok-hooks.json so the adapter,
+ * not Grok, ends a slow body and records it. SessionEnd: Grok bounds each SessionEnd hook by its own
+ * timeout (default 1.5 s, 10-hooks.md:477-478); 2200 ms sits under the 3 s registration.
+ */
+export function budgetFor(hookId, event) {
+  if (event === 'SessionEnd') return 2_200;
+  if (hookId === 'decision-gate') return 6_500;
+  if (hookId === 'grounding-stamp' || hookId === 'grounding-turn-mark') return 4_000;
+  return 8_500;
+}
+
+/** Grok payload -> the Claude-shaped payload the shared bodies read. Pure. */
+export function grokToBrainPayload(input) {
+  const out = normalizeHostEvent(input && typeof input === 'object' ? input : {});
+  if (out.prompt_id === undefined && typeof input?.promptId === 'string') out.prompt_id = input.promptId;
+  delete out.transcript_path;
+  delete out.transcriptPath;
+  return out;
+}
+
+/** True for Grok's session-end observe-only Stop fire, which is not a turn (10-hooks.md:399, :502). */
+export function isSessionEndStop(payload) {
+  return payload?.hook_event_name === 'Stop' && typeof payload.reason === 'string' && payload.reason !== 'end_turn';
+}
+
+/**
+ * The body's result -> what this process writes and its exit code. Pure, so the contract test can
+ * drive every branch without a host.
+ */
+export function grokOutput({ hookId, event, status, stdout = '', stderr = '' }) {
+  if (status === 2 && GROK_BLOCKING_HOOKS.has(hookId) && event === 'PreToolUse') {
+    return { stdout: isJson(stdout) ? stdout : '', stderr: stderr || 'RuvNet Brain decision-gate refused this write.\n', code: 2 };
+  }
+  if (status !== 0 || !GROK_OUTPUT_EVENTS.has(event)) return { stdout: '', stderr: '', code: 0 };
+  const text = String(stdout || '').trim();
+  if (!text) return { stdout: '', stderr: '', code: 0 };
+  if (isJson(text)) return { stdout: text, stderr: '', code: 0 };
+  if (event === 'Stop') return { stdout: '', stderr: '', code: 0 };
+  return { stdout: JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }), stderr: '', code: 0 };
+}
+
+function isJson(text) {
+  try { const v = JSON.parse(text); return Boolean(v) && typeof v === 'object' && !Array.isArray(v); } catch { return false; }
+}
+
+function readStdin(limit = 1024 * 1024) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let bytes = 0;
+    let done = false;
+    let idle;
+    const finish = () => { if (done) return; done = true; clearTimeout(idle); process.stdin.pause(); resolve(Buffer.concat(chunks).toString('utf8')); };
+    const arm = () => { clearTimeout(idle); idle = setTimeout(finish, 150); };
+    process.stdin.on('data', (chunk) => {
+      if (bytes < limit) { const kept = chunk.subarray(0, limit - bytes); chunks.push(kept); bytes += kept.length; }
+      arm();
+    });
+    process.stdin.once('end', finish);
+    process.stdin.once('error', finish);
+    arm();
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  if (developmentHooksSuspended()) return 0;
+  const hookId = process.argv[2] || '';
+  const extra = process.argv.slice(3);
+  const raw = await readStdin();
+  let input = {};
+  try { input = raw ? JSON.parse(raw) : {}; } catch { /* the bodies fail soft on an empty payload */ }
+  if (typeof input.cwd === 'string' && developmentHooksSuspended(input.cwd)) return 0;
+  const payload = grokToBrainPayload(input);
+  const event = String(payload.hook_event_name || '');
+  if (isSessionEndStop(payload)) return 0;
+
+  const projectDir = String(payload.cwd || process.env.GROK_WORKSPACE_ROOT || process.cwd());
+  let cwd = process.cwd();
+  try { if (fs.statSync(projectDir).isDirectory()) cwd = projectDir; } catch { /* keep the default */ }
+  const budget = budgetFor(hookId, event);
+  const env = {
+    ...process.env,
+    CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
+    CLAUDE_PROJECT_DIR: projectDir,
+    CLAUDE_SESSION_ID: String(payload.session_id || process.env.GROK_SESSION_ID || ''),
+    RUVNET_HOOK_HOST: 'grok',
+  };
+  const r = spawnSync(process.execPath, [path.join(HERE, 'hook-shim.mjs'), hookId, ...extra], {
+    input: JSON.stringify(payload), encoding: 'utf8', env, cwd, timeout: budget, killSignal: 'SIGKILL',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (r.error?.code === 'ETIMEDOUT' || r.signal === 'SIGKILL') {
+    try {
+      const { recordHookFailure } = await import(pathToFileURL(path.join(HERE, 'hook-failures.mjs')).href);
+      recordHookFailure({ hook: hookId, event, error: 'killed-by-grok-adapter', limitMs: budget });
+    } catch { /* an unrecordable failure must not become a second one */ }
+    return 0;
+  }
+  const out = grokOutput({ hookId, event, status: r.status, stdout: r.stdout, stderr: r.stderr });
+  if (out.stdout) fs.writeSync(1, out.stdout);
+  if (out.stderr) fs.writeSync(2, out.stderr);
+  return out.code;
+}
+
+const isMain = (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (isMain) process.exit(await main().catch(() => 0));

package/plugin/scripts/hook-failures.mjs

@@ -8,6 +8,7 @@
  */
 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]';
@@ -43,3 +44,18 @@ export function failureLine(brainHome, { advance = true } = {}) {
   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

package/plugin/scripts/learn-capture.mjs

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