ruvnet-brain 4.5.6 → 4.5.8

package/plugin/mcp/managed-cli-interface.mjs

@@ -2,11 +2,14 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { managedGenerationIdentity } from './managed-cli-generation.mjs';
 import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
 import { projectDirectory } from '../scripts/project-identity.mjs';
 import { recordManagedCliObservation, recordRegistryLatestObservation } from '../scripts/capability-claim-evidence.mjs';
 import { runSessionSnapshotHook } from '../scripts/session-snapshot-hook.mjs';
 import { resolveProjectStore } from '../scripts/project-store-resolver.mjs';
+import { isAutomaticProgressionSuspension } from '../scripts/project-progression-suspension.mjs';
 
 export const MANAGED_EXECUTABLES = Object.freeze([
   'ruflo',
@@ -34,6 +37,12 @@ const MAX_ARG_BYTES = 8192;
 const DEFAULT_FRESH_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 1024 * 1024;
+// Bind direct calls to the module loaded at process start, too. Missing shell resources do not
+// prevent declarations from loading; the active dispatcher supplies the execution binding.
+const LOCAL_BINDING = (() => {
+  try { return managedGenerationIdentity(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')).binding; }
+  catch { return null; }
+})();
 
 const executableSchema = {
   type: 'string',
@@ -139,27 +148,32 @@ function stateDir(env) {
   return env.RUVNET_BRAIN_HELP_READ_DIR || path.join(brainHome, 'help-read');
 }
 
-function freshStamp(executable, argv, env, now = Date.now()) {
+function freshStamp(executable, argv, env, binding, now = Date.now()) {
   const stamp = path.join(stateDir(env), helpKey(executable, argv));
-  let stat;
+  let stat; let readAt;
   try {
-    stat = fs.statSync(stamp);
+    stat = fs.lstatSync(stamp);
+    if (!stat.isFile()) return false;
+    const receipt = JSON.parse(fs.readFileSync(stamp, 'utf8'));
+    if (receipt.schemaVersion !== 1 || receipt.generation !== binding
+      || !Number.isFinite(receipt.readAt) || receipt.readAt > now) return false;
+    readAt = receipt.readAt;
   } catch {
     return false;
   }
   const configured = Number(env.RUVNET_BRAIN_HELP_MAX_AGE_MS);
   const maxAge = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_FRESH_MS;
-  return now - stat.mtimeMs < maxAge;
+  return now - stat.mtimeMs < maxAge && now - readAt < maxAge;
 }
 
-function writeStamps(executable, argv, env) {
+function writeStamps(executable, argv, env, binding) {
   const dir = stateDir(env);
   fs.mkdirSync(dir, { recursive: true });
   for (const key of stampKeysForHelp(executable, argv)) {
     const stamp = path.join(dir, key);
     const temporary = path.join(dir, `.${key}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
     try {
-      fs.writeFileSync(temporary, '', { flag: 'wx', mode: 0o600 });
+      fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, generation: binding, readAt: Date.now() }), { flag: 'wx', mode: 0o600 });
       fs.renameSync(temporary, stamp);
     } finally {
       try { fs.unlinkSync(temporary); } catch { /* renamed or never created */ }
@@ -291,7 +305,8 @@ function managedProgressionCapture({ executable, argv, projectRoot, env, event,
       },
     } : {}),
   };
-  return { adopted: true, ...runSessionSnapshotHook(projectRoot, event, { rawInput: JSON.stringify(payload), host }) };
+  const result = runSessionSnapshotHook(projectRoot, event, { rawInput: JSON.stringify(payload), host, env });
+  return isAutomaticProgressionSuspension(result) ? result : { adopted: true, ...result };
 }
 
 function resultOf(executable, argv, result) {
@@ -316,6 +331,8 @@ function resultOf(executable, argv, result) {
 
 export async function callManagedCli(toolName, args, env = process.env, fetchImpl = globalThis.fetch, lifecycle = {}) {
   try {
+    const binding = lifecycle.generationBinding || LOCAL_BINDING;
+    if (!binding) throw new Error('managed generation identity unavailable');
     const executable = assertExecutable(args?.executable);
     const argv = literalArgv(args?.argv ?? []);
     const projectRoot = env.RUVNET_BRAIN_PROJECT_DIR || projectDirectory({ env });
@@ -344,13 +361,13 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
       stampKeysForHelp(executable, argv);
       const commandArgv = [...argv, '--help'];
       const execution = await execute(executable, commandArgv, env);
-      if (execution.code === 0 && !execution.error) writeStamps(executable, argv, env);
+      if (normalizeManagedExecution(execution).outcome === 'success') writeStamps(executable, argv, env, binding);
       recordManagedCliObservation({ toolName, executable, argv: commandArgv, execution, env });
       return resultOf(executable, commandArgv, execution);
     }
 
     if (toolName === 'ruvnet_cli_run') {
-      if (!freshStamp(executable, argv, env)) {
+      if (!freshStamp(executable, argv, env, binding)) {
         const key = helpKey(executable, argv).replaceAll('.', ' ');
         return {
           content: [{ type: 'text', text: `Read the interface first with ruvnet_cli_help for: ${key}` }],
@@ -391,7 +408,8 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
         : env;
       const capture = typeof lifecycle.capture === 'function' ? lifecycle.capture : managedProgressionCapture;
       const beforeCapture = await capture({ executable, argv, projectRoot, env: childEnv, event: 'PreToolUse' });
-      if (beforeCapture?.error || (beforeCapture?.adopted && beforeCapture.progressionCaptured !== true)) {
+      if (beforeCapture?.error || (beforeCapture?.adopted && beforeCapture.progressionCaptured !== true
+        && !isAutomaticProgressionSuspension(beforeCapture))) {
         const reason = beforeCapture.error || beforeCapture.skipped || 'pre-execution progression was not durably captured';
         return { content: [{ type: 'text', text: `managed execution refused: ${reason}` }], isError: true };
       }
@@ -405,13 +423,19 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
         await lifecycle.afterExecute({ executable, argv, projectRoot, env: childEnv, execution, normalized });
       }
       recordManagedCliObservation({ toolName, executable, argv, execution, env });
-      if (afterCapture?.adopted && afterCapture.progressionCaptured !== true) {
+      if (afterCapture?.adopted && afterCapture.progressionCaptured !== true
+        && !isAutomaticProgressionSuspension(afterCapture)) {
         return {
           content: [{ type: 'text', text: `managed command ${normalized.outcome}; continuity result was not durably captured: ${afterCapture.skipped || 'unknown reason'}` }],
           isError: true,
         };
       }
-      return resultOf(executable, argv, execution);
+      const result = resultOf(executable, argv, execution);
+      if (isAutomaticProgressionSuspension(beforeCapture) || isAutomaticProgressionSuspension(afterCapture)) {
+        result.content.push({ type: 'text', text: 'Automatic project progression is operator-suspended; suspended captures produced no progression receipt. Ordinary AgentDB memory and explicit checkpoints remain available.' });
+        result.structuredContent.continuity = 'operator-suspended';
+      }
+      return result;
     }
 
     return {

package/plugin/mcp/server.mjs

@@ -35,7 +35,8 @@ import os from 'node:os';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { writeOwn as writeOwnReadiness } from '../scripts/mcp-readiness.mjs';
-import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
+import { MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
+import { dispatchManagedCli } from './managed-cli-generation.mjs';
 import { unmountedNotice } from '../scripts/brain-location.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
@@ -362,7 +363,7 @@ async function handleClient(msg) {
     case 'tools/call': {
       if (params?.name === 'ruvnet_cli_help' || params?.name === 'ruvnet_cli_run'
         || params?.name === 'ruvnet_registry_latest') {
-        return clientOk(id, await callManagedCli(params.name, params.arguments || {}));
+        return clientOk(id, await dispatchManagedCli(params.name, params.arguments || {}));
       }
       if (params?.name !== 'search_ruvnet') return clientErr(id, -32602, `unknown tool: ${params?.name}`);
       refreshLease();

package/plugin/scripts/agentdb-recall.mjs

@@ -14,6 +14,9 @@ import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
 import { rufloCwdFor, rufloScratchRoot } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { isHarnessGenerated, readStdinBounded } from './hook-input.mjs';
+import { learningContext } from './runtime-preferences.mjs';
+import { learningTarget, LEARNING_NAMESPACE } from './learning-store.mjs';
+import { safeAction } from './learning-queue.mjs';
 
 import { redactText } from './continuity-events.mjs';
 export const STORE_FILES = Object.freeze(['memory.db']);
@@ -146,11 +149,22 @@ export function evidenceExcerpt(value, key, prompt = '') {
   return clean(start >= 0 ? text.slice(start) : text, 110);
 }
 
+export function learningObservationExcerpt(raw) {
+  try {
+    const row = JSON.parse(raw);
+    if (Object.keys(row).sort().join(',') !== 'action,authoritative,outcome,provenance,schemaVersion,scope,tool'
+      || row.schemaVersion !== 1 || row.authoritative !== false || row.provenance !== 'system-observation'
+      || row.outcome !== 'host-reported-success' || !['project', 'user'].includes(row.scope)
+      || !['Bash', 'Write', 'Edit', 'MultiEdit'].includes(row.tool) || safeAction(row.tool, row.action) !== row.action) return null;
+    return `Unratified host-reported success: ${row.tool} ${row.action}. Verify current results.`;
+  } catch { return null; }
+}
+
 export function pickRows(results, limit = 3) {
   const candidates = results.flatMap((r) => r.rows.filter((p) => p.namespace === r.namespace && (!NOISE_KEY.test(p.key) || p.namespace === 'turns' && /^turn[-_]/i.test(p.key))
     && (!r.family || p.key.toLowerCase().includes(r.family))
-    && Number.isFinite(p.score) && p.score >= MIN_RELEVANCE).map((p) => ({ ...p, targeted: Boolean(r.family) })));
-  const signal = (p) => SIGNAL_NAMESPACES.has(p.namespace) ? 2 : p.namespace === 'turns' ? 1 : 0;
+    && Number.isFinite(p.score) && p.score >= MIN_RELEVANCE).map((p) => ({ ...p, storePath: r.storePath, targeted: Boolean(r.family) })));
+  const signal = (p) => SIGNAL_NAMESPACES.has(p.namespace) ? 2 : p.namespace === 'turns' ? 1 : p.namespace === LEARNING_NAMESPACE ? -1 : 0;
   const ranked = candidates.sort((a, b) => Number(b.targeted) - Number(a.targeted) || signal(b) - signal(a) || b.score - a.score);
   // Curated lessons and patterns are signal; lifecycle transcript telemetry is not.
   // Do not reserve a slot for a weak match just because its namespace was searched.
@@ -159,7 +173,7 @@ export function pickRows(results, limit = 3) {
     if (chosen.length >= limit) break;
     if (!chosen.some((r) => r.key === row.key && r.namespace === row.namespace)) chosen.push(row);
   }
-  return chosen.map((p) => ({ store: 'memory.db', key: p.key, namespace: p.namespace,
+  return chosen.map((p) => ({ store: 'memory.db', ...(p.storePath ? { storePath: p.storePath } : {}), key: p.key, namespace: p.namespace,
     score: p.score, preview: clean(p.preview, 110) }));
 }
 
@@ -227,7 +241,15 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     const budget = Number.isFinite(requested) && requested > 0 ? Math.min(requested, 1900) : DEFAULT_DEADLINE_MS;
     const deadline = started + budget;
     const { root, stores } = agentdbStores(projectDir, Math.max(1, Math.min(100, Math.floor(budget / 4))));
-    if (!stores.length) return empty;
+    let learningStore;
+    try {
+      const context = learningContext({ env, cwd: root });
+      if (context.enabled) {
+        const db = learningTarget(context, { env });
+        if (fs.lstatSync(db).isFile()) learningStore = { name: 'memory.db', path: db };
+      }
+    } catch { /* No global fallback: only an explicitly authorized existing learning store. */ }
+    if (!stores.length && !learningStore) return empty;
     const bin = ruflo === undefined ? resolveRuflo({ env }) : ruflo;
     if (!bin) return { ...empty, stores };
     const store = stores[0];
@@ -238,10 +260,15 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
       : /where are we|status|catch me up/i.test(prompt) ? 'project-state-current'
       : /releas|publish|workflow run|dispatch/i.test(prompt) ? 'release'
       : /requirement|always|every prompt/i.test(prompt) ? 'decision-agentdb' : null;
-    const jobs = namespaces.flatMap((namespace) => [{ namespace, family: null, args: ['--format', 'json', '-q', query, '-n', namespace, '--limit', '12'] },
-      ...(family && !SIGNAL_NAMESPACES.has(namespace) && namespace !== 'turns' ? [{ namespace, family, args: ['--format', 'json', '-q', family, '-n', namespace, '-t', 'keyword', '--limit', '4'] }] : [])]);
-    const results = await Promise.all(jobs.map(async ({ namespace, family: recordFamily, args }) => ({ namespace, family: recordFamily,
-      ...await searchOnce({ ruflo: bin, store, deadline, env, scratch: scratchFor, args }) })));
+    const jobs = (store ? namespaces : []).flatMap((namespace) => [{ store, namespace, family: null, args: ['--format', 'json', '-q', query, '-n', namespace, '--limit', '12'] },
+      ...(family && !SIGNAL_NAMESPACES.has(namespace) && namespace !== 'turns' ? [{ store, namespace, family, args: ['--format', 'json', '-q', family, '-n', namespace, '-t', 'keyword', '--limit', '4'] }] : [])]);
+    const words = promptKeywords(prompt, 14);
+    const workflowQuery = words.map(word => safeAction('Bash', word))
+      .find(action => action && action !== 'command');
+    if (learningStore && workflowQuery) jobs.push({ store: learningStore, namespace: LEARNING_NAMESPACE, family: null,
+      args: ['--format', 'json', '-q', workflowQuery, '-n', LEARNING_NAMESPACE, '-t', 'keyword', '--limit', '4'] });
+    const results = await Promise.all(jobs.map(async ({ store: jobStore, namespace, family: recordFamily, args }) => ({ namespace, family: recordFamily, storePath: jobStore.path,
+      ...await searchOnce({ ruflo: bin, store: jobStore, deadline, env, scratch: scratchFor, args }) })));
     let status = results.every((r) => r.state === 'ok') ? 'ok'
       : results.some((r) => r.state === 'timed out') ? 'timed out' : 'unavailable';
     // Overfetch a bounded six exact values so rejected turn metadata cannot hide
@@ -250,11 +277,12 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     // Ruflo previews are ~60 characters. Read the actual selected values within
     // the same deadline so the block contains useful evidence rather than titles.
     const retrieved = await Promise.all(candidates.map(async (p) => {
-      const r = await searchOnce({ ruflo: bin, store, deadline, env, scratch: scratchFor, operation: 'retrieve',
+      const r = await searchOnce({ ruflo: bin, store: { name: 'memory.db', path: p.storePath }, deadline, env, scratch: scratchFor, operation: 'retrieve',
         args: ['-k', p.key, '-n', p.namespace, '--value-only'] });
       if (r.state === 'ok' && r.value && !r.value.startsWith('[WARN]')) {
         const clauses = p.namespace === 'turns' ? turnOutcomeClauses(r.value, prompt) : null;
-        const preview = clauses ? turnOutcomeExcerpt(r.value, prompt) : evidenceExcerpt(r.value, p.key, prompt);
+        const preview = p.namespace === LEARNING_NAMESPACE ? learningObservationExcerpt(r.value)
+          : clauses ? turnOutcomeExcerpt(r.value, prompt) : evidenceExcerpt(r.value, p.key, prompt);
         return { pick: preview ? { ...p, preview, clauses } : null, state: 'ok' };
       }
       return { pick: null, state: r.state === 'ok' ? 'unavailable' : r.state };

package/plugin/scripts/continuation-gate.mjs

@@ -385,7 +385,9 @@ function promiseBookkeeping() {
       }
     }
     const openKeys = new Set(led.items.filter((i) => i?.kind === PROMISE_KIND && !i.done && i.projectId === pid).map((i) => i.key));
-    for (const promise of extractCommitments(hookInput.last_assistant_message)) {
+    // Owner preference suppresses only new capture; verified closure above and integrity audits stay active.
+    const newPromises = process.env.RUVNET_PROMISE_CAPTURE === 'off' ? [] : extractCommitments(hookInput.last_assistant_message);
+    for (const promise of newPromises) {
       if (openKeys.has(promise.key) || openKeys.size >= PROMISE_CAP_OPEN) continue;
       openKeys.add(promise.key);
       led.items.push({ schemaVersion: 1, kind: PROMISE_KIND, text: promise.text, key: promise.key, done: false, at,

package/plugin/scripts/continuity-hook-policy.mjs

@@ -123,6 +123,7 @@ const registration = (id, matcher, hosts) => Object.freeze({ id, matcher, hosts:
 export const CONTINUITY_EVENTS = Object.freeze({
   SessionStart: Object.freeze([
     registration('session-start', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
+    registration('learn-flush', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
   ]),
   UserPromptSubmit: Object.freeze([
     registration('session-snapshot', '*', ['claude', 'codex']),
@@ -153,6 +154,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
   // no change either (proven live: the real MCP tool_response's `content[0].text` carries the exact
   // "Searched N RuvNet repos" banner and query text the script already looks for).
   PostToolUse: Object.freeze([
+    registration('learn-capture', '^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$', ['claude', 'codex']),
     registration('session-snapshot', '*', ['claude', 'codex']),
     registration('grounding-stamp', '^(?:.*__)?search_ruvnet$', ['claude', 'codex']),
   ]),
@@ -184,6 +186,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
     registration('session-snapshot', '*', ['claude']),
   ]),
   SessionEnd: Object.freeze([
+    registration('learn-flush', '*', ['claude', 'codex']),
     registration('session-snapshot', '*', ['claude', 'codex']),
   ]),
 });

package/plugin/scripts/continuity-journal.mjs

@@ -303,24 +303,24 @@ export function recordingLine(status, now = Date.now()) {
   return `AgentDB: recording ✓ (last write ${ago(now - status.lastCommitAt)} ago, ${status.eventsToday} event(s) today, outbox ${status.pending} pending)`;
 }
 
-/**
- * The Claude Stop line, at most ONCE per session per condition (review S3: it repeated at every turn).
- * State is a tiny file in the project's own .swarm, bounded to the last 20 sessions.
- */
-export function stopNotice({ journal, status, session }) {
-  if (!status?.stuck || !status.problem) return '';
-  const file = path.join(journal.swarm, NOTICE_STATE);
+/** Shared notices: once per session/condition, bounded to the last twenty sessions in .swarm. */
+export function conditionNotice({ swarm, session, condition, message, now = Date.now }) {
+  const file = path.join(swarm, NOTICE_STATE);
   let state = {};
   try { state = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { /* first notice */ }
   const id = String(session || 'unknown');
   const shown = Array.isArray(state[id]?.conditions) ? state[id].conditions : [];
-  if (shown.includes(status.problem)) return '';
-  state[id] = { at: new Date(journal.now()).toISOString(), conditions: [...shown, status.problem] };
+  if (shown.includes(condition)) return '';
+  state[id] = { at: new Date(now()).toISOString(), conditions: [...shown, condition] };
   const recent = Object.entries(state).sort((a, b) => String(b[1]?.at).localeCompare(String(a[1]?.at))).slice(0, 20);
   try { fs.writeFileSync(file, JSON.stringify(Object.fromEntries(recent)), { mode: 0o600 }); } catch { /* still show it once */ }
-  return `[RuvNet Brain] ${recordingLine(status, journal.now())}`;
+  return message;
+}
+export function stopNotice({ journal, status, session }) {
+  if (!status?.stuck || !status.problem) return '';
+  return conditionNotice({ swarm: journal.swarm, session, condition: status.problem, now: () => journal.now(),
+    message: `[RuvNet Brain] ${recordingLine(status, journal.now())}` });
 }
-
 function defaultStore({ ruflo, db, key, value }) {
   const cwd = rufloRunDir(db);
   try {

package/plugin/scripts/hook-shim.mjs

@@ -86,7 +86,8 @@ catch (e) { BRAIN_OFF = !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
 const TABLE = {
   'session-start':    { file: 'session-start-core.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'partial' },
   'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence', stdinBytes: 32768 },
-  'capacity-aware-parallel-work': { file: 'capacity-aware-parallel-work.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 32768 },
+  // Capacity advice is a Brain prompt hint; OFF must not execute its resource probes or steer work.
+  'capacity-aware-parallel-work': { file: 'capacity-aware-parallel-work.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'silence', stdinBytes: 32768 },
   // ADR-063 / issue #103: `blocking` so an opt-in refusal can actually reach the host. The hook
   // still exits 0 for every user at the shipped default (managedMemoryBoundary=advise), so this
   // changes the CEILING of what it may do, not what it does.
@@ -118,7 +119,7 @@ const TABLE = {
   // own header already says: "remains reachable through hook-shim's dispatch table by explicit
   // 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.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
+  '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.

package/plugin/scripts/kb-copy-proof.mjs

@@ -2,20 +2,23 @@
 //
 // kb-copy-proof.mjs — may a full copy of the knowledge base be deleted? The ONE proof used by the
 // footprint sweep (plugin/scripts/brain-footprint.mjs) and by the installer right after it activates a
-// new generation (bin/install.mjs unzipInto). Pure read; never follows a link; never writes.
+// new generation (bin/install.mjs unzipInto). Pure read; checks KB-root ancestors and file/link types
+// before comparing content; never writes.
 //
 // A copy is DISPOSABLE only when nothing in it is unique. Every file must be one of:
 //   * a PRIVATE-store file (names from the PRIVATE-STORES.json fence of the live brain AND of the copy, plus
 //     every updateManaged:false store in either SOURCE.json; membership rule = kb/forge-update.mjs
 //     capturePrivateOverlayState) that exists BYTE-IDENTICAL at the same path in the live brain — nothing
 //     else excuses a private file;
-//   * a public release file: listed with these exact bytes in the copy's own ARCHIVE-MANIFEST.json, or a
-//     name the live generation ships, or a member of a public store family (named by either COVERAGE.json
+//   * a file whose regular-file bytes survive exactly at the same path in live, or a public release file
+//     listed with these exact bytes in the copy's own ARCHIVE-MANIFEST.json, or a public store family (named by either COVERAGE.json
 //     or the live SOURCE.json) that a newer release replaced or retired;
 //   * installer-written or reinstallable (node_modules/, the updater/validator files the installer places);
 //   * a symbolic link identical in the live brain (links are compared, never followed).
 // Anything else — a user's own file, an unfenced store, a link the live brain lacks — KEEPS the copy, and
-// is named. The live brain itself must be present, so a copy is never removed while it may be the only one.
+// is named. Paths are checked for symlink ancestors within both KB roots before any exemption; host
+// aliases above those roots (such as macOS /tmp) are not traversed as part of this check. Invalid metadata,
+// unreadable inventory and special file types keep the copy. The live brain itself must be present.
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
@@ -29,13 +32,13 @@ const sha256File = (file) => crypto.createHash('sha256').update(fs.readFileSync(
 /** Every regular file and link under `root`, relative, without following links. macOS volume metadata
  * (AppleDouble `._*` shadows on an exFAT disk, .DS_Store, …) is the volume's, never a copy's unique data. */
 function walk(root, prefix = '', out = []) {
-  for (const name of names(path.join(root, prefix)).filter((n) => !isVolumeMetadata(n))) {
+  for (const name of fs.readdirSync(path.join(root, prefix)).sort().filter((n) => !isVolumeMetadata(n))) {
     const relative = prefix ? path.join(prefix, name) : name;
-    const st = lstat(path.join(root, relative));
-    if (!st) continue;
+    const st = fs.lstatSync(path.join(root, relative));
     if (st.isSymbolicLink()) out.push({ relative, link: true });
     else if (st.isDirectory()) walk(root, relative, out);
     else if (st.isFile()) out.push({ relative, link: false, size: st.size });
+    else throw new Error(`unsupported file type: ${relative}`);
   }
   return out;
 }
@@ -46,10 +49,11 @@ const storeList = (source) => {
   return stores && typeof stores === 'object' ? Object.entries(stores).map(([kbName, value]) => ({ kbName, ...value })) : [];
 };
 const stemOf = (file) => path.basename(String(file)).replace(/(?:\.big)?\.rvf$/i, '').toLowerCase();
-// The store a sidecar belongs to: <store>.big.rvf[.embed|.idmap].json, <store>.meta.json, <store>.passages.jsonl,
-// <store>.symbols.json, <store>-primer.md.
+// The store a sidecar belongs to: <store>.big.rvf[.embed|.idmap].json, <store>[.big].meta.json,
+// <store>[.big].passages.jsonl, <store>[.big].symbols.json, <store>-primer.md.
 const storeStem = (file) => path.basename(String(file)).toLowerCase()
-  .replace(/-primer\.md$/, '').replace(/(?:\.big)?\.rvf(?:\.[a-z]+\.json)?$/, '').replace(/\.(?:meta|symbols)\.json$|\.passages\.jsonl$/, '');
+  .replace(/-primer\.md$/, '').replace(/(?:\.big)?\.rvf(?:\.[a-z]+\.json)?$/, '')
+  .replace(/(?:\.big)?(?:\.(?:meta|symbols)\.json|\.passages\.jsonl)$/, '');
 // Files the installer/updater writes into a KB that no bundle ships (bin/install.mjs placeUpdater,
 // placeTrustedCoverageValidator, ensureVerifier; the updater's snapshot receipt). Re-created on every install.
 const INSTALLER_WRITTEN = new Set(['coverage-integrity.mjs', 'RUNTIME-IDENTITY.json', '.refresh-snapshot.json',
@@ -87,6 +91,54 @@ const sameBytes = (left, right) => {
   try { return sha256File(left) === sha256File(right); } catch { return false; }
 };
 
+function safeAncestors(root, relative) {
+  let dir = root;
+  for (const part of ['', ...relative.split(path.sep).slice(0, -1)]) {
+    if (part) dir = path.join(dir, part);
+    let stat;
+    try { stat = fs.lstatSync(dir); }
+    catch (error) { return error.code === 'ENOENT'; } // a retired public path may be absent in live
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+  }
+  return true;
+}
+
+function metadataFailure(root) {
+  for (const file of ['SOURCE.json', 'PRIVATE-STORES.json', 'RVF-GENERATIONS.json',
+    'COVERAGE.json', 'ARCHIVE-MANIFEST.json', 'repo-aliases.json']) {
+    const full = path.join(root, file);
+    let stat;
+    try { stat = fs.lstatSync(full); }
+    catch (error) { if (error.code === 'ENOENT' && file !== 'SOURCE.json') continue; return `${file}: ${error.message}`; }
+    try {
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('not a regular metadata file');
+      const value = JSON.parse(fs.readFileSync(full, 'utf8'));
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not a metadata object');
+      if (file === 'PRIVATE-STORES.json' && Object.hasOwn(value, 'privateStores')
+        && (!Array.isArray(value.privateStores) || value.privateStores.some((name) => typeof name !== 'string' || !name.trim()))) {
+        throw new Error('private store fence is malformed');
+      }
+      if (file === 'SOURCE.json' && Object.hasOwn(value, 'stores')) {
+        if (!value.stores || typeof value.stores !== 'object'
+          || Object.values(value.stores).some((store) => !store || typeof store !== 'object' || Array.isArray(store))) {
+          throw new Error('store metadata is malformed');
+        }
+        if (storeList(value).some((store) => !store || typeof store !== 'object'
+          || (store.updateManaged === false && (typeof store.kbName !== 'string' || !store.kbName.trim())))) {
+          throw new Error('private store metadata is malformed');
+        }
+      }
+      if (file === 'RVF-GENERATIONS.json' && Object.hasOwn(value, 'stores')
+        && (!value.stores || typeof value.stores !== 'object' || Array.isArray(value.stores)
+          || Object.values(value.stores).some((generation) => !generation || typeof generation !== 'object'
+            || typeof generation.file !== 'string' || !generation.file.trim()))) throw new Error('generation metadata is malformed');
+      if (file === 'COVERAGE.json' && value.rows != null && !Array.isArray(value.rows)) throw new Error('coverage rows are malformed');
+      if (file === 'ARCHIVE-MANIFEST.json' && value.files != null && !Array.isArray(value.files)) throw new Error('archive inventory is malformed');
+    } catch (error) { return `${file}: ${error.message}`; }
+  }
+  return null;
+}
+
 /**
  * @returns {{disposable: boolean, unique: {file: string, why: string}[], reason: string}} — a kept copy
  * always names the files that keep it.
@@ -95,13 +147,19 @@ export function kbCopyProof({ copyDir, liveDir }) {
   const copy = lstat(copyDir);
   if (!copy || copy.isSymbolicLink() || !copy.isDirectory()) return { disposable: false, unique: [], reason: 'not a real directory (a link is never entered)' };
   const live = lstat(liveDir);
-  if (!live || !live.isDirectory() || !readJson(path.join(liveDir, 'SOURCE.json'))
-    || !names(liveDir).some((name) => /\.rvf$/i.test(name))) {
+  if (!live || !live.isDirectory()) {
+    return { disposable: false, unique: [], reason: 'the live brain is missing or incomplete, so this copy may be the only good one' };
+  }
+  for (const root of [copyDir, liveDir]) {
+    const failure = metadataFailure(root);
+    if (failure) return { disposable: false, unique: [], reason: `unreadable or malformed metadata in ${root}: ${failure}` };
+  }
+  if (!names(liveDir).some((name) => /\.rvf$/i.test(name) && lstat(path.join(liveDir, name))?.isFile())) {
     return { disposable: false, unique: [], reason: 'the live brain is missing or incomplete, so this copy may be the only good one' };
   }
   const privateNames = privateStoreNames([liveDir, copyDir]);
-  const generations = readJson(path.join(copyDir, 'RVF-GENERATIONS.json'))?.stores || {};
-  const privateArtifacts = Object.entries(generations).filter(([name]) => privateNames.has(name.toLowerCase()))
+  const generations = [copyDir, liveDir].flatMap((dir) => Object.entries(readJson(path.join(dir, 'RVF-GENERATIONS.json'))?.stores || {}));
+  const privateArtifacts = generations.filter(([name]) => privateNames.has(name.toLowerCase()))
     .map(([, g]) => String(g?.file || '')).filter(Boolean).map((file) => ({ directory: path.dirname(path.normalize(file)),
       basename: path.basename(file).toLowerCase(), stem: stemOf(file) }));
   const coverageNames = (dir) => (readJson(path.join(dir, 'COVERAGE.json'))?.rows || [])
@@ -118,15 +176,10 @@ export function kbCopyProof({ copyDir, liveDir }) {
   let files;
   try { files = walk(copyDir); } catch (error) { return { disposable: false, unique, reason: `unreadable copy: ${error.message}` }; }
   for (const { relative, link, size } of files) {
-    // node_modules (npm reinstalls it) and .console-runtime (bin/install.mjs installConsoleRuntime re-places it)
-    if (['node_modules', '.console-runtime'].includes(relative.split(path.sep)[0])
-      || (!relative.includes(path.sep) && INSTALLER_WRITTEN.has(relative))) continue;
     const isPrivate = belongsToPrivate(relative, privateNames, privateArtifacts);
     const inLive = path.join(liveDir, relative);
-    if (link) {
-      const liveLink = lstat(inLive);
-      const same = liveLink?.isSymbolicLink() && fs.readlinkSync(inLive) === fs.readlinkSync(path.join(copyDir, relative));
-      if (!same) unique.push({ file: relative, why: 'a symbolic link the live brain does not have (never followed)' });
+    if (!safeAncestors(copyDir, relative) || !safeAncestors(liveDir, relative)) {
+      unique.push({ file: relative, why: 'unsafe path ancestor inside a KB root (never followed)' });
       continue;
     }
     if (isPrivate) {
@@ -135,10 +188,19 @@ export function kbCopyProof({ copyDir, liveDir }) {
       }
       continue;
     }
+    // Private membership above takes precedence over reinstallable runtime and release exemptions.
+    if (['node_modules', '.console-runtime'].includes(relative.split(path.sep)[0])
+      || (!relative.includes(path.sep) && INSTALLER_WRITTEN.has(relative))) continue;
+    if (link) {
+      const liveLink = lstat(inLive);
+      const same = liveLink?.isSymbolicLink() && fs.readlinkSync(inLive) === fs.readlinkSync(path.join(copyDir, relative));
+      if (!same) unique.push({ file: relative, why: 'a symbolic link the live brain does not have (never followed)' });
+      continue;
+    }
     if (relative === 'ARCHIVE-MANIFEST.json' && shipped.size) continue; // the release manifest itself
     const listed = shipped.get(relative);
     if (listed && listed.bytes === size && listed.sha256 === sha256File(path.join(copyDir, relative))) continue;
-    if (lstat(inLive)) continue; // a release-owned name the live generation ships (same or newer bytes)
+    if (sameBytes(path.join(copyDir, relative), inLive)) continue; // existence alone proves no ownership or redundancy
     if (publicNames.has(storeStem(relative))) continue; // a public store family a newer release replaced or retired
     unique.push({ file: relative, why: 'not in the live brain, not in this copy\'s release manifest, not a public store' });
   }

package/plugin/scripts/learn-capture.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// PostToolUse captures only a fixed workflow vocabulary, then schedules bounded orphan recovery.
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readStdinBounded } from './hook-input.mjs';
+import { learningContext } from './runtime-preferences.mjs';
+import { learningTarget } from './learning-store.mjs';
+import { safeQueue, safeAction, writeExclusive, takeQueueLock, releaseQueueLock } from './learning-queue.mjs';
+
+try {
+  const context = learningContext();
+  if (!context.enabled) process.exit(0);
+  const raw = await readStdinBounded({ maxBytes: 65536, emptyMs: 150 });
+  const input = JSON.parse(raw.toString());
+  if (input.hook_event_name && input.hook_event_name !== 'PostToolUse') process.exit(0);
+  const response = input.tool_response;
+  if (typeof response === 'string') {
+    const exit = /^Process exited with code (-?\d+)\s*$/m.exec(response);
+    if ((exit && Number(exit[1]) !== 0) || /Process running with session ID/.test(response)) process.exit(0);
+  }
+  if (input.error || input.is_error === true || response?.error || response?.interrupted === true || response?.signal
+    || response?.success === false || response?.is_error === true || response?.isError === true
+    || [response?.exit_code, response?.exitCode, response?.status].some(value => Number.isInteger(value) && value !== 0)) process.exit(0);
+  const tool = input.tool_name;
+  if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(tool)) process.exit(0);
+  const action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
+  if (!action) process.exit(0);
+  const fresh = learningContext();
+  if (!fresh.enabled || fresh.queueDir !== context.queueDir) process.exit(0);
+  learningTarget(fresh); // Existing authorized user store is required before creating any user queue bytes.
+  const dir = safeQueue(fresh, true);
+  const sid = createHash('sha256').update(String(input.session_id || process.env.CLAUDE_SESSION_ID || 'default')).digest('hex').slice(0, 24);
+  writeExclusive(path.join(dir, `session-${sid}-${randomUUID()}.jsonl`), JSON.stringify({ tool, action }) + '\n');
+  // Per-scope lock in the flusher suppresses duplicate workers; capture never waits on the learner.
+  const token = takeQueueLock(fresh);
+  if (!token) process.exit(0);
+  const child = spawn(process.execPath, [fileURLToPath(new URL('./learn-flush.mjs', import.meta.url)), '--supervisor'], {
+    cwd: fresh.projectDir, detached: true, stdio: 'ignore', windowsHide: true, env: { ...process.env, RUVNET_LEARN_WORKER_TOKEN: token },
+  });
+  child.on('error', () => releaseQueueLock(fresh, token)); child.unref();
+} catch { /* advisory transport; unsafe/malformed input produces no persisted payload */ }
+process.exit(0);