ruvnet-brain 4.7.16 → 4.7.18

package/plugin/scripts/degradation-watch.mjs

@@ -52,6 +52,7 @@ import path from 'node:path';
 // is the exact defect class this file exists to close. Caught by counting occurrences, not by
 // reading the code and believing it.
 import { fileURLToPath } from 'node:url';
+import { rufloRunDir } from './ruflo-bin.mjs';
 
 /**
  * THE PROBE TARGET IS A SCRATCH DB, NOT THE PROJECT'S.
@@ -73,8 +74,19 @@ import { fileURLToPath } from 'node:url';
  */
 const defaultDb = () => path.join(os.tmpdir(), `ruvnet-durability-probe-${process.pid}.db`);
 
+// ruflo writes into its cwd on every call (.claude/, .claude-flow/, ruvector.db, agentdb.rvf) and its startup
+// self-update runs `npm install @claude-flow/cli --save-exact` there. This probe runs on every `git push`, so with the
+// caller's cwd it could leave those in the user's project (measured 2026-10-22: a 1.4 GB node_modules and a
+// package.json in a project). It now runs in a private scratch dir, removed after the call, with both switches off.
 function defaultRun(cmd, args) {
-  return execFileSync(cmd, args, { encoding: 'utf8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'] });
+  let cwd = null;
+  try { cwd = rufloRunDir(path.join(os.tmpdir(), 'ruvnet-durability-probe')); } catch { /* fall back to tmp below */ }
+  try {
+    return execFileSync(cmd, args, { cwd: cwd || os.tmpdir(), encoding: 'utf8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false' } });
+  } finally {
+    if (cwd) { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later as a stale run- dir */ } }
+  }
 }
 
 /**

package/plugin/scripts/developer-update-policy.mjs

@@ -32,17 +32,43 @@ export function normalizeNpmDistTags(value) {
   }
   return value;
 }
-export function pickTargetTag(tags, want = 'latest', defaultTag = 'latest') {
-  const candidates = [...new Set([want, defaultTag])].filter(tag => typeof tags?.[tag] === 'string');
+export function normalizeNpmTimes(value) {
+  // `npm view <pkg> time --json`: an object of version -> ISO time (npm 12 wraps it in a one-record array).
+  if (Array.isArray(value)) value = value.length === 1 ? value[0] : null;
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+/**
+ * The newer of {want, defaultTag} by version — EXCEPT a non-default tag whose version was published BEFORE the
+ * default tag's version. That is an abandoned pre-release line, not a newer build: measured 2026-10-23, agentic-flow
+ * `alpha` = 3.0.0-alpha.2 (published 2026-03-25) against `latest` = 2.1.4 (2026-10-09); by version alone the alpha
+ * channel would install seven-month-old code. `published` is `npm view <pkg> time`; without it, ordering is unchanged.
+ */
+export function pickTargetTag(tags, want = 'latest', defaultTag = 'latest', { published = null } = {}) {
+  const at = (version) => Date.parse(published?.[version] ?? '');
+  // `published` null: the caller did not ask, ordering is by version. An object: times were REQUIRED, so a missing or
+  // unreadable time makes the non-default tag unverifiable and it is skipped (cross-model review 2026-10-24: a failed
+  // lookup must not let a seven-month-old pre-release through).
+  const abandoned = (tag) => tag !== defaultTag && typeof tags?.[defaultTag] === 'string' && published !== null
+    && (!Number.isFinite(at(tags[tag])) || !Number.isFinite(at(tags[defaultTag])) || at(tags[tag]) < at(tags[defaultTag]));
+  const candidates = [...new Set([want, defaultTag])].filter(tag => typeof tags?.[tag] === 'string' && !abandoned(tag));
   candidates.sort((a, b) => cmpVersion(tags[b], tags[a]));
   return { tag: candidates[0] || null, target: tags?.[candidates[0]] || null };
 }
-export function selectTag(name, current, tags, channel = 'latest') {
+/** Whether choosing between `want` and `latest` needs publish times: only when the two tags name different versions. */
+export function needsPublishTimes(tags, want) {
+  return want !== 'latest' && typeof tags?.[want] === 'string' && typeof tags?.latest === 'string' && tags[want] !== tags.latest;
+}
+/** The ONE answer to "which tag does this package track": shared by the updater and the stack-sync notice. */
+export function wantedTag(name, channel = 'latest') {
   if (!['latest', 'alpha'].includes(channel)) throw Error('unsupported update channel');
   // Kit's installed release contract uses next; never convert it to an npm alpha alias.
+  return name === '@pacphi/agentic-kit' ? 'next' : FAMILY.test(name) && channel === 'alpha' ? 'alpha' : 'latest';
+}
+export function selectTag(name, current, tags, channel = 'latest', { published = null } = {}) {
+  const wanted = wantedTag(name, channel);
   tags = normalizeNpmDistTags(tags);
-  const wanted = name === '@pacphi/agentic-kit' ? 'next' : FAMILY.test(name) && channel === 'alpha' ? 'alpha' : 'latest';
-  const { tag, target: version } = pickTargetTag(tags, wanted);
+  const times = published === null || published === undefined ? null : (normalizeNpmTimes(published) || {});
+  const { tag, target: version } = pickTargetTag(tags, wanted, 'latest', { published: times });
   if (!tag) throw Error(`no allowed release tag: ${name}`);
   return { tag, version, upgrade: cmpVersion(version, current) > 0, ahead: cmpVersion(version, current) < 0 };
 }

package/plugin/scripts/developer-update.mjs

@@ -6,7 +6,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
-import { cmpVersion as compare, selectTag, FAMILY, PLUGIN_MARKETPLACES, REVIEWED_INSTALL_SCRIPTS, EXECUTION_MODULES } from './developer-update-policy.mjs';
+import { cmpVersion as compare, selectTag, needsPublishTimes, normalizeNpmDistTags, wantedTag, FAMILY, PLUGIN_MARKETPLACES, REVIEWED_INSTALL_SCRIPTS, EXECUTION_MODULES } from './developer-update-policy.mjs';
 import { acquireDeveloperLock, sharedLockStatus } from './developer-update-lock.mjs';
 import { maintenance } from './developer-update-maintenance.mjs';
 import { cleanupNpxDuplicates } from './developer-update-cleanup.mjs';
@@ -31,7 +31,7 @@ export function atomic(file, value) {
 function invoke(command, args, { cwd = HOME, timeout = 600_000, allowed = [0], env = process.env, capture = false } = {}) {
   const r = spawnSync(command, args, { cwd, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024,
     env: { ...env, PATH: [...new Set([path.dirname(NODE), path.join(env.npm_config_prefix || PREFIX, process.platform === 'win32' ? '' : 'bin'), ...(env.PATH || '').split(path.delimiter)])].join(path.delimiter),
-      CI: '1', DISABLE_AUTOUPDATER: '1', GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', GH_PROMPT_DISABLED: '1', HOMEBREW_NO_INSTALL_CLEANUP: '1', HOMEBREW_NO_AUTO_UPDATE: '1', RUVNET_BRAIN_HOME: env.RUVNET_BRAIN_HOME || CACHE } });
+      CI: '1', DISABLE_AUTOUPDATER: '1', CLAUDE_FLOW_AUTO_UPDATE: 'false', GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', GH_PROMPT_DISABLED: '1', HOMEBREW_NO_INSTALL_CLEANUP: '1', HOMEBREW_NO_AUTO_UPDATE: '1', RUVNET_BRAIN_HOME: env.RUVNET_BRAIN_HOME || CACHE } });
   if (!capture && (r.error || !allowed.includes(r.status))) throw Error(`${path.basename(command)} ${args[0]}: ${r.error?.message || `exit ${r.status}`}: ${(r.stderr || r.stdout || '').trim().slice(-600)}`);
   return { stdout: (r.stdout || '').trim(), stderr: (r.stderr || '').trim(), exitCode: r.status, error: r.error?.message || null };
 }
@@ -120,7 +120,7 @@ function verifyPackage(before, expected, run) {
   }
   return after;
 }
-export function upgradePackage(before, tags, scripts = REVIEWED_INSTALL_SCRIPTS, { run = invokeText, dryRun = false, channel = 'latest', npm = NPM, preservePackages = [] } = {}) {
+export function upgradePackage(before, tags, scripts = REVIEWED_INSTALL_SCRIPTS, { run = invokeText, dryRun = false, channel = 'latest', npm = NPM, preservePackages = [], published = null } = {}) {
   // Snapshot identity must still exist and own the original paths before any installer runs.
   if (before.localSource && before.rawLink !== undefined) {
     if (!fs.lstatSync(before.location).isSymbolicLink() || fs.readlinkSync(before.location) !== before.rawLink) throw Error(`source link changed before preservation: ${before.name}`);
@@ -133,7 +133,7 @@ export function upgradePackage(before, tags, scripts = REVIEWED_INSTALL_SCRIPTS,
   if (live.localSource) return { name: before.name, state: 'local-source-preserved', before, after: live };
   if (live.launchers.some(b => !b.real)) throw Error(`absent launcher: ${before.name}`);
   if (live.launchers.some(b => !b.owned)) return { name: before.name, state: 'shadowed-preserved', before, after: live };
-  const target = selectTag(before.name, before.version, tags, channel);
+  const target = selectTag(before.name, before.version, tags, channel, { published });
   if (preservePackages.includes(before.name)) return { name: before.name, state: 'local-modification-preserved', reason: 'preservedLocalModification', target, before, after: live };
   if (!target.upgrade || dryRun) return { name: before.name, state: target.upgrade ? 'update-available' : target.ahead ? 'ahead-preserved' : 'current', target, before, after: live };
   const spec = `${before.name}@${target.tag}`;
@@ -422,7 +422,19 @@ export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(),
     persistReceipt();
     for (const before of receipt.before) {
       const tags = before.localSource ? {} : JSON.parse(run(npm, ['view', before.name, 'dist-tags', '--json'], { timeout: 90_000 }));
-      receipt.steps.push(upgradePackage(before, tags, REVIEWED_INSTALL_SCRIPTS, { run, dryRun: mode === 'check', channel: config.channel, npm, preservePackages: config.preservePackages }));
+      // A tracked non-latest tag (alpha, Kit's next) needs publish times to tell a newer pre-release from an abandoned
+      // one (developer-update-policy pickTargetTag); fetched only when that tag and latest name different versions. A
+      // failed lookup is {} — required but unknown — so the pre-release is skipped, never installed blind.
+      let published = null;
+      if (!before.localSource) {
+        let needed = false;
+        try { needed = needsPublishTimes(normalizeNpmDistTags(tags), wantedTag(before.name, config.channel)); } catch { needed = false; }
+        if (needed) {
+          try { published = JSON.parse(run(npm, ['view', before.name, 'time', '--json'], { timeout: 90_000 })); }
+          catch { published = {}; }
+        }
+      }
+      receipt.steps.push(upgradePackage(before, tags, REVIEWED_INSTALL_SCRIPTS, { run, dryRun: mode === 'check', channel: config.channel, npm, preservePackages: config.preservePackages, published }));
       persistReceipt();
     }
     receipt.plugins = await synchronizePlugins(run, mode === 'check', receipt.notes, { home, prefix, scope: config.scope, locate, unattended: !!env.RUVNET_NIGHTLY_IDENTITY });

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

@@ -48,11 +48,14 @@ export const GROK_OUTPUT_EVENTS = Object.freeze(new Set(['PreToolUse', 'PostTool
 
 /**
  * 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.
+ * not Grok, ends a slow body and records it. SessionEnd: "A plugin's SessionEnd hook runs for at most
+ * that default [1.5 s], whatever its timeout" (10-hooks.md:644-645), so the budget sits under 1500 ms and
+ * is handed to the body (RUVNET_CODEX_BUDGET_MS, the host-budget seam the Codex wrapper already uses), which
+ * then detaches its checkpoint instead of starting an inline store+readback Grok would kill partway.
  */
+export const SESSION_END_BUDGET_MS = 1_400;
 export function budgetFor(hookId, event) {
-  if (event === 'SessionEnd') return 2_200;
+  if (event === 'SessionEnd') return SESSION_END_BUDGET_MS;
   if (hookId === 'decision-gate') return 6_500;
   if (hookId === 'grounding-stamp' || hookId === 'grounding-turn-mark') return 4_000;
   return 8_500;
@@ -133,6 +136,7 @@ async function main() {
     CLAUDE_PROJECT_DIR: projectDir,
     CLAUDE_SESSION_ID: String(payload.session_id || process.env.GROK_SESSION_ID || ''),
     RUVNET_HOOK_HOST: 'grok',
+    ...(event === 'SessionEnd' ? { RUVNET_CODEX_BUDGET_MS: String(budget) } : {}), // the body plans inside Grok's 1.5 s
   };
   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',

package/plugin/scripts/hook-failures.mjs

@@ -9,16 +9,21 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { createHash } from 'node:crypto';
 
 export const FAILURE_FILE = 'hook-failures.jsonl';
 export const FAILURE_LINE_PREFIX = '[RuvNet Brain — HOOK FAILURES]';
 const CURSOR_FILE = 'hook-failures.cursor';
+const WINDOW_FILE = 'hook-failures.window.json';
 const MAX_READ = 256 * 1024;
+export const REPEAT_WINDOW_MS = 10 * 60_000;
+const MAX_WINDOWS = 64;
 
 /** Summarize failures recorded after the cursor; advance it. Returns '' when there is nothing new. */
-export function failureLine(brainHome, { advance = true } = {}) {
+export function failureLine(brainHome, { advance = true, now = Date.now() } = {}) {
   const file = path.join(brainHome, FAILURE_FILE);
   const cursorFile = path.join(brainHome, CURSOR_FILE);
+  try { flushRepeats(brainHome, now, { all: true }); } catch { /* the rows already on disk are still reported */ } // the report is now
   let size;
   try { size = fs.statSync(file).size; } catch { return ''; }
   let offset = 0;
@@ -33,29 +38,92 @@ export function failureLine(brainHome, { advance = true } = {}) {
   if (advance) { try { fs.writeFileSync(cursorFile, JSON.stringify({ offset: size })); } catch { /* re-reported next session */ } }
   if (!rows.length) return '';
   const byHook = new Map();
+  let total = 0;
   for (const r of rows) {
     const id = String(r.hook || 'unknown').slice(0, 40);
-    const why = r.note ? String(r.note).split(':')[0].slice(0, 48) : r.error ? String(r.error).slice(0, 40) : r.signal ? String(r.signal) : `exit ${r.status}`;
+    const why = r.note ? String(r.note).split(':')[0].slice(0, 48) : r.error ? String(r.error).replace(/ \(repeated\)$/, '').slice(0, 40) : r.signal ? String(r.signal) : `exit ${r.status}`;
     const e = byHook.get(id) || { n: 0, why: new Set() };
-    e.n += 1; e.why.add(why); byHook.set(id, e);
+    const n = Number(r.count) > 0 ? Number(r.count) : 1; // an aggregated row stands for `count` runs
+    e.n += n; total += n; e.why.add(why); byHook.set(id, e);
   }
   const parts = [...byHook.entries()].sort((a, b) => b[1].n - a[1].n)
     .map(([id, e]) => `${id} ×${e.n} (${[...e.why].slice(0, 3).join(', ')})`);
-  return `${FAILURE_LINE_PREFIX} ${rows.length} advisory hook run(s) did not complete or did not resolve since ${rows[0].at}: ${parts.join('; ')}. `
+  return `${FAILURE_LINE_PREFIX} ${total} advisory hook run(s) did not complete or did not resolve since ${rows[0].at}: ${parts.join('; ')}. `
     + `They failed open. Details: ${file}`;
 }
 
+function appendRow(brainHome, row) {
+  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(row)}\n`, { mode: 0o600 });
+}
+
+/** Hashes and long numbers vary per row (`workflow-<sha>`, pids, ms, timestamps); short ones (exit codes, counts) are the error. */
+export const normalizeFailure = (text) => String(text || '').replace(/[0-9a-f]{16,}/gi, '*').replace(/\d{5,}/g, 'N').slice(0, 160);
+const windowFile = (brainHome) => path.join(brainHome, WINDOW_FILE);
+/**
+ * A window entry must be one this module could have written: a real epoch `at` no later than one window ahead (a
+ * Date cannot hold -1e300 or 1e300, and 8.64e15+1 never expires), an integer count ≥ 1, string hook and error.
+ * Entries failing that are dropped, the rest kept; any other file shape is an empty window file.
+ */
+const validWindow = (w, now) => w && typeof w === 'object' && !Array.isArray(w) && Number.isFinite(w.at) && w.at >= 0 && w.at <= now + REPEAT_WINDOW_MS
+  && Number.isInteger(w.count) && w.count >= 1 && typeof w.hook === 'string' && typeof w.error === 'string';
+function loadWindows(brainHome, now) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(windowFile(brainHome), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return Object.fromEntries(Object.entries(parsed).filter(([, w]) => validWindow(w, now)));
+  } catch { return {}; }
+}
+function saveWindows(brainHome, windows) { // rename, so a concurrent reader never sees a torn file
+  const tmp = `${windowFile(brainHome)}.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(windows), { mode: 0o600 }); fs.renameSync(tmp, windowFile(brainHome));
+}
+
+/** A closed window whose repeats were held back becomes ONE row carrying their count. */
+function closeWindow(brainHome, w, now) {
+  if (w.count > 1) appendRow(brainHome, { at: new Date(now).toISOString(), hook: w.hook, event: w.event, error: `${w.error} (repeated)`, count: w.count - 1, since: new Date(w.at).toISOString() });
+}
+
+/** Close the expired windows; `all` closes the open ones too (SessionStart reports now). Returns the windows left open. */
+function flushRepeats(brainHome, now, { all = false } = {}) {
+  const windows = loadWindows(brainHome, now);
+  let changed = false;
+  for (const [sig, w] of Object.entries(windows)) {
+    if (!all && now - w.at < REPEAT_WINDOW_MS) continue;
+    try { closeWindow(brainHome, w, now); } catch { /* one bad window must not stop the others being reported */ }
+    delete windows[sig]; changed = true;
+  }
+  if (changed) try { saveWindows(brainHome, windows); } catch { /* the rows are written; the window file is a cache */ }
+  return windows;
+}
+
 /**
  * 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.
+ *
+ * REPEATS ARE COUNTED, NOT APPENDED (measured 2026-10-21: 1,162 rows, 826 of them one learn-capture failure
+ * repeated, so the real failures were invisible). The first occurrence of (hook, event, normalized error)
+ * is a row at once; repeats inside REPEAT_WINDOW_MS only increment a count in hook-failures.window.json,
+ * and the window closes as ONE row carrying `count`. Distinct errors keep distinct rows. The window file has no
+ * lock: two writers racing can lose an increment (under-count), and two processes closing the same expired window
+ * can both write its count row (over-count). Tolerated: the ledger is a signal, never an audit. The first row is
+ * appended BEFORE its window is saved, so a failed append never leaves a window claiming a row that is not there.
  */
-export function recordHookFailure(fields, { brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain') } = {}) {
+export function recordHookFailure(fields, { brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'), now = Date.now() } = {}) {
   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 });
+    const windows = flushRepeats(brainHome, now);
+    const error = normalizeFailure(fields.error ?? fields.note ?? (fields.signal || `exit ${fields.status}`));
+    const sig = createHash('sha256').update(`${fields.hook}\0${fields.event || ''}\0${error}`).digest('hex').slice(0, 16);
+    if (windows[sig]) { windows[sig].count += 1; saveWindows(brainHome, windows); return true; }
+    appendRow(brainHome, { at: new Date(now).toISOString(), ...fields });
+    windows[sig] = { at: now, count: 1, hook: fields.hook, event: fields.event || '', error };
+    const oldest = Object.keys(windows).sort((a, b) => windows[a].at - windows[b].at).slice(0, Math.max(0, Object.keys(windows).length - MAX_WINDOWS));
+    for (const old of oldest) { closeWindow(brainHome, windows[old], now); delete windows[old]; } // bounded: the oldest close early
+    try { saveWindows(brainHome, windows); } catch { /* the row is on disk; the next repeat starts a fresh window */ }
     return true;
   } catch { return false; }
 }

package/plugin/scripts/learn-capture.mjs

@@ -1,14 +1,66 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import os from 'node:os';
+import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readStdinBounded } from './hook-input.mjs';
 import { learningContext } from './runtime-preferences.mjs';
-import { recordLearningObservation, distillObservations } from './learning-store.mjs';
+import { recordLearningObservation, distillObservations, observationKey } from './learning-store.mjs';
 import { resolveRuflo } from './ruflo-bin.mjs';
 import { recordHookFailure } from './hook-failures.mjs';
 
+// LOAD BOUNDS (measured 2026-10-21: one busy session spawned hundreds of concurrent detached `ruflo memory store`
+// children, which timed out against each other and wrote 826 ledger rows in a day). Owner ruling 2026-10-12 stands:
+// no local queue, no replay — an observation that finds no slot is DROPPED and counted.
+export const OBSERVE_SLOTS = 2;           // detached --observe children alive at once, per Brain home
+export const SLOT_STALE_MS = 60_000;      // a slot older than this, or held by a dead pid, is reclaimed
+export const COALESCE_MS = 10 * 60_000;   // an identical observation key inside this window does not spawn again
+const defaultBrainHome = (env) => env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
+const learnDir = (brainHome, sub) => { const dir = path.join(brainHome, 'learn-capture', sub); fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); return dir; };
+
+/** Parent-side coalescing: marker file per key under `learn-capture/recent/`, pruned when it grows past 256 entries. */
+export function recentlyCaptured(brainHome, key, now = Date.now()) {
+  try { return now - fs.statSync(path.join(learnDir(brainHome, 'recent'), key)).mtimeMs < COALESCE_MS; } catch { return false; }
+}
+export function markCaptured(brainHome, key, now = Date.now()) {
+  const dir = learnDir(brainHome, 'recent');
+  try { fs.writeFileSync(path.join(dir, key), '', { mode: 0o600 }); } catch { return; }
+  const names = fs.readdirSync(dir);
+  if (names.length > 256) for (const name of names) { try { if (now - fs.statSync(path.join(dir, name)).mtimeMs >= COALESCE_MS) fs.unlinkSync(path.join(dir, name)); } catch { /* raced */ } }
+}
+
+function slotStale(slot, now) {
+  let held;
+  try { held = JSON.parse(fs.readFileSync(slot, 'utf8')); } catch { try { return now - fs.statSync(slot).mtimeMs > SLOT_STALE_MS; } catch { return false; } }
+  if (!Number.isInteger(held?.pid) || now - Number(held.at) > SLOT_STALE_MS) return true;
+  try { process.kill(held.pid, 0); return false; } catch (error) { return error.code === 'ESRCH'; }
+}
+/** O_EXCL slot files `learn-capture/slots/slot-N`; a stale one is reclaimed by rename, so only one claimant wins it. */
+export function acquireObserveSlot(brainHome, now = Date.now()) {
+  const dir = learnDir(brainHome, 'slots');
+  for (let i = 0; i < OBSERVE_SLOTS; i += 1) {
+    const slot = path.join(dir, `slot-${i}`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try { fs.writeFileSync(slot, JSON.stringify({ pid: process.pid, at: now }), { flag: 'wx', mode: 0o600 }); return slot; } catch (error) { if (error.code !== 'EEXIST') break; }
+      if (!slotStale(slot, now)) break;
+      const claim = `${slot}.reclaim-${process.pid}`;
+      try { fs.renameSync(slot, claim); fs.unlinkSync(claim); } catch { break; } // another claimant took it
+    }
+  }
+  return null;
+}
+export function releaseObserveSlot(slot, pid = process.pid) {
+  try { if (JSON.parse(fs.readFileSync(slot, 'utf8')).pid === pid) fs.unlinkSync(slot); } catch { /* reclaimed already */ }
+}
+
+/** Every shed is one fixed-string ledger call; hook-failures.mjs's own window counts the repeats on one row. */
+export const SHED_ERROR = 'shed observation (load)';
+export function shedObservation(brainHome) {
+  recordHookFailure({ hook: 'learn-capture', event: 'PostToolUse', error: SHED_ERROR }, { brainHome });
+  return false;
+}
+
 // 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(' '));
@@ -30,7 +82,7 @@ export function safeAction(tool, value) {
  * session-snapshot's PostToolUse boundary. learningContext() owns consent and brain-off. A refused or
  * unverified write is LOUD: one row in the hook-failures ledger, summarized at the next SessionStart.
  */
-export function captureLearning(input, { env = process.env, binary = resolveRuflo({ env }), brainHome, detach = false } = {}) {
+export function captureLearning(input, { env = process.env, binary = resolveRuflo({ env }), brainHome = defaultBrainHome(env), detach = false } = {}) {
   let tool; let action;
   try {
     const context = learningContext();
@@ -48,24 +100,37 @@ export function captureLearning(input, { env = process.env, binary = resolveRufl
     if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(tool)) return false;
     action = safeAction(tool, tool === 'Bash' ? input.tool_input?.command : 'edit file');
     if (!action) return false;
-    if (!binary) throw new Error('ruflo not found');
+    if (!binary) throw new Error('ruflo not found'); // one ledger row per 10 min: recordHookFailure counts the repeats
     const observation = { tool, action, session: String(input.session_id || '') };
+    const key = observationKey(observation);
+    if (recentlyCaptured(brainHome, key)) return true; // identical observation already captured this window: no process
     // 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 });
+    if (detach) {
+      const slot = acquireObserveSlot(brainHome);
+      if (!slot) return shedObservation(brainHome);
+      markCaptured(brainHome, key);
+      return detachLearning('--observe', { env: { ...env, RUFLO_BIN: binary }, brainHome, observation, slot });
+    }
     recordLearningObservation(binary, context, observation, { env, deadline: Date.now() + 6000 });
+    markCaptured(brainHome, key);
     return true;
   } catch (error) {
-    if (tool && action) recordHookFailure({ hook: 'learn-capture', event: 'PostToolUse', error: String(error?.message || error).slice(0, 160) }, brainHome ? { brainHome } : undefined);
+    if (tool && action) recordHookFailure({ hook: 'learn-capture', event: 'PostToolUse', error: String(error?.message || error).slice(0, 160) }, { brainHome });
     return false;
   }
 }
 
-/** Detached, bounded child (`--observe` one observation, `--distill` the namespace). Only fixed-vocabulary fields cross. */
-export function detachLearning(mode, { env = process.env, brainHome, observation } = {}) {
+/**
+ * Detached, bounded child (`--observe` one observation, `--distill` the namespace). Only fixed-vocabulary fields
+ * cross. The parent's resolved ruflo travels as RUFLO_BIN (resolveRuflo's authoritative seam), so the child never
+ * re-resolves it; the slot it holds travels as RUVNET_LEARN_SLOT and is re-stamped with the child's pid.
+ */
+export function detachLearning(mode, { env = process.env, brainHome, observation, slot } = {}) {
   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 } : {}) } });
+    env: { ...env, ...(observation ? { RUVNET_LEARN_OBSERVATION: JSON.stringify(observation) } : {}), ...(brainHome ? { RUVNET_BRAIN_HOME: brainHome } : {}), ...(slot ? { RUVNET_LEARN_SLOT: slot } : {}) } });
   child.unref();
+  if (slot) { try { fs.writeFileSync(slot, JSON.stringify({ pid: child.pid, at: Date.now() }), { mode: 0o600 }); } catch { /* reclaimed by age */ } }
   return true;
 }
 
@@ -80,7 +145,7 @@ function runDetached(mode) {
     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); }
+  } catch (error) { fail(error); } finally { if (process.env.RUVNET_LEARN_SLOT) releaseObserveSlot(process.env.RUVNET_LEARN_SLOT); }
 }
 
 const isMain = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();

package/plugin/scripts/learning-store.mjs

@@ -32,7 +32,7 @@ export function runLearningRuflo(binary, args, db, { env = process.env, deadline
   const cwd = rufloRunDir(db, { root: env.RUVNET_RUFLO_CWD_ROOT || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.cache', 'ruvnet-brain', 'learning-ruflo') });
   try {
     const invocation = rufloInvocation(binary, args);
-    return spawnSync(invocation.executable, invocation.args, { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' },
+    return spawnSync(invocation.executable, invocation.args, { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false' },
       encoding: 'utf8', shell: false, timeout: Math.min(maxStepMs, remaining), killSignal: 'SIGKILL', maxBuffer: 65536, windowsHide: true });
   } finally { fs.rmSync(cwd, { force: true, recursive: true }); }
 }
@@ -42,22 +42,32 @@ export function runLearningRuflo(binary, args, db, { env = process.env, deadline
  * No local queue, no worker, no replay (owner ruling 2026-10-12): a failure throws to the caller, which
  * records it in the hook-failures ledger so SessionStart reports it.
  */
+// DETERMINISTIC per (session, tool, action) (review N1): with --no-upsert, rUv's store itself dedupes, so a
+// session holds at most one row per distinct pair and concurrent writers of the same pair collapse.
+export const observationKey = ({ session = '', tool, action }) => 'workflow-' + createHash('sha256').update(JSON.stringify([String(session), tool, action])).digest('hex');
+
 export function recordLearningObservation(binary, context, { tool, action, session = '' }, options = {}) {
   const db = learningTarget(context, options);
-  // DETERMINISTIC per (session, tool, action) (review N1): with --no-upsert, rUv's store itself dedupes, so a
-  // session holds at most one row per distinct pair and concurrent writers of the same pair collapse.
-  const key = 'workflow-' + createHash('sha256').update(JSON.stringify([session, tool, action])).digest('hex');
+  const key = observationKey({ session, tool, action });
   const value = JSON.stringify({ schemaVersion: 1, tool, action, scope: context.scope,
     authoritative: false, provenance: 'system-observation', outcome: 'host-reported-success' });
   const run = args => { if (options.allowed && !options.allowed()) throw new Error('learning consent changed'); return runLearningRuflo(binary, args, db, options); };
   const stored = run(['memory', 'store', '--key', key, '--value', value, '--namespace', LEARNING_NAMESPACE,
     '--no-upsert', '--provenance', 'system_observation', '--path', db]);
   const retrieved = run(['memory', 'retrieve', '--key', key, '--namespace', LEARNING_NAMESPACE, '--value-only', '--path', db]);
-  const exact = !retrieved.error && retrieved.status === 0 && String(retrieved.stdout || '').trim() === value;
-  // A refused store whose key already holds these exact bytes is the dedupe working, not a failure.
+  const readBack = !retrieved.error && retrieved.status === 0 ? String(retrieved.stdout || '').trim() : null;
+  const exact = readBack === value;
+  // A refused store whose key already holds these exact bytes is the dedupe working, not a failure (idempotent).
+  // Measured 2026-10-21: 141 ledger rows said "already exists" because the readback itself had timed out, so the
+  // row blamed the store; the reason names which step failed, and a key holding DIFFERENT bytes stays a failure.
   if (stored.error || stored.status !== 0) {
     if (exact) return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true, alreadyStored: true };
-    throw new Error(`ruflo memory store refused the observation: ${captureFailureReason(stored, stored.status)}`);
+    const reason = captureFailureReason(stored, stored.status);
+    if (/already exists/i.test(reason)) {
+      if (readBack !== null) throw new Error('duplicate key holds a different observation');
+      throw new Error(`exact readback of the existing key failed: ${captureFailureReason(retrieved, retrieved.status)}`);
+    }
+    throw new Error(`ruflo memory store refused the observation: ${reason}`);
   }
   if (!exact) throw new Error('canonical exact CLI readback failed');
   return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true };

package/plugin/scripts/nightly-scheduler.mjs

@@ -147,17 +147,23 @@ const BRIDGED_UPDATE_MODULES = [...HISTORICAL_UPDATE_MODULES, 'developer-update-
 const LEGACY_UPDATE_MODULES = [...BRIDGED_UPDATE_MODULES, 'developer-update-policy.mjs'];
 const PREVIOUS_DEVELOPER_MODULES = [...BRIDGED_UPDATE_MODULES, ...EXECUTION_MODULES.filter(name => name !== 'plugin-artifact-proof.mjs')];
 const DEVELOPER_UPDATE_MODULES = [...new Set([...LEGACY_UPDATE_MODULES, ...EXECUTION_MODULES])];
-function updateModules(directory, sourceDir = path.dirname(fileURLToPath(import.meta.url)), developerSuite = true) {
+/** The shipped module set and the content digest it is registered under (`update-modules-<digest>`); reads only. */
+function readModuleSet(sourceDir, developerSuite) {
   const files = developerSuite ? DEVELOPER_UPDATE_MODULES : LEGACY_UPDATE_MODULES;
   const bytes = Object.fromEntries(files.map(file => [file, fs.readFileSync(path.join(sourceDir, file))]));
-  const digest = sha256(Buffer.concat(files.flatMap(file => [Buffer.from(file), bytes[file]])));
+  return { files, bytes, digest: sha256(Buffer.concat(files.flatMap(file => [Buffer.from(file), bytes[file]]))) };
+}
+const registeredModuleDigest = (record) => /^update-modules-([a-f0-9]{64})$/.exec(path.basename(path.dirname(record.updateModules?.['automatic-update.mjs']?.path || '')))?.[1] || null;
+
+function updateModules(directory, sourceDir = path.dirname(fileURLToPath(import.meta.url)), developerSuite = true, { write = true } = {}) {
+  const { files, bytes, digest } = readModuleSet(sourceDir, developerSuite);
   const target = path.join(directory, `update-modules-${digest}`);
-  fs.mkdirSync(target, { recursive: true });
+  if (write) fs.mkdirSync(target, { recursive: true });
   return Object.fromEntries(files.map(file => {
     const dest = path.join(target, file);
     const hash = sha256(bytes[file]);
-    if (fs.existsSync(dest) && sha256(fs.readFileSync(dest)) !== hash) throw new Error('immutable update module was changed');
-    if (!fs.existsSync(dest)) fs.writeFileSync(dest, bytes[file], { mode: 0o600 });
+    if (write && fs.existsSync(dest) && sha256(fs.readFileSync(dest)) !== hash) throw new Error('immutable update module was changed');
+    if (write && !fs.existsSync(dest)) fs.writeFileSync(dest, bytes[file], { mode: 0o600 });
     return [file, { path: dest, sha256: hash }];
   }));
 }
@@ -174,31 +180,80 @@ function verifyUpdateModules(modules) {
   }
 }
 
+/**
+ * The ONE writer of a nightly registration. `dryRun` builds the exact record it WOULD write (runner, modules, record)
+ * and writes nothing — the refresh path compares that candidate before any rename. `environment`: undefined derives
+ * the allowlisted values from env; an object is kept verbatim; null omits the field (an older registration without it).
+ */
 export function installNightlyRunner({ brainHome, source, nodePath = process.execPath,
-  identity = NIGHTLY_LABEL, packageTarget, bundleTarget, env = {}, moduleSource, developerSuite = !NIGHTLY_PROOF_LABEL.test(identity) } = {}) {
+  identity = NIGHTLY_LABEL, packageTarget, bundleTarget, env = {}, environment, moduleSource, developerSuite = !NIGHTLY_PROOF_LABEL.test(identity), dryRun = false } = {}) {
   validateIdentity(identity);
   if (!source || !fs.existsSync(source)) throw new Error(`nightly runner source is missing: ${source || '(unset)'}`);
   const bytes = fs.readFileSync(source);
   const digest = sha256(bytes);
   const dir = path.join(brainHome, 'scheduler');
   const runnerPath = path.join(dir, `nightly-refresh-${digest}.mjs`);
-  fs.mkdirSync(dir, { recursive: true });
-  if (fs.existsSync(runnerPath) && sha256(fs.readFileSync(runnerPath)) !== digest) {
-    throw new Error(`nightly runner at ${runnerPath} does not match its content-addressed identity`);
+  if (!dryRun) {
+    fs.mkdirSync(dir, { recursive: true });
+    if (fs.existsSync(runnerPath) && sha256(fs.readFileSync(runnerPath)) !== digest) {
+      throw new Error(`nightly runner at ${runnerPath} does not match its content-addressed identity`);
+    }
+    if (!fs.existsSync(runnerPath)) fs.writeFileSync(runnerPath, bytes, { mode: 0o755 });
   }
-  if (!fs.existsSync(runnerPath)) fs.writeFileSync(runnerPath, bytes, { mode: 0o755 });
-  const modules = updateModules(dir, moduleSource, developerSuite);
+  const modules = updateModules(dir, moduleSource, developerSuite, { write: !dryRun });
   const record = { updateModules: modules, ...(developerSuite ? { mode: 'developer-suite' } : {}), schemaVersion: 2, kind: 'ruvnet-brain-nightly-scheduler', identity,
     nodePath: path.resolve(nodePath), runnerPath, runnerSha256: digest, argv: [],
-    environment: Object.fromEntries(NIGHTLY_ENV_ALLOWLIST.filter(key => env[key] !== undefined).map(key => [key, key === 'PATH' ? automaticPath({ nodePath, home: homeOf(env), env }) : String(env[key])])),
+    ...(environment === null ? {} : { environment: environment ?? Object.fromEntries(NIGHTLY_ENV_ALLOWLIST.filter(key => env[key] !== undefined).map(key => [key, key === 'PATH' ? automaticPath({ nodePath, home: homeOf(env), env }) : String(env[key])])) }),
     packageTarget: normalizePackageTarget(packageTarget), bundleTarget: normalizeBundleTarget(bundleTarget, identity) };
   const recordPath = path.join(dir, registrationName(identity));
+  if (dryRun) return { ...record, recordPath };
   const tmp = `${recordPath}.tmp-${process.pid}`;
   fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`);
   fs.renameSync(tmp, recordPath);
   return { ...record, recordPath };
 }
 
+export const NIGHTLY_ENABLE_FIX = 'npx ruvnet-brain@latest --enable-nightly';
+export const NIGHTLY_UPDATE_FIX = 'npx ruvnet-brain@latest --update';
+/**
+ * Does the registered nightly run the code installed now? The scheduler executes a content-addressed snapshot of
+ * the update modules that only --enable-nightly used to refresh (measured 2026-10-22: the 4.7.15 developer-update
+ * fix shipped to disk and the 03:30 job still ran the old module). Pure read: `current`, `stale` (modules only;
+ * --update refreshes them), `runner-changed` (the LaunchAgent command would change: explicit enablement only),
+ * or `unregistered`.
+ */
+export function nightlyModuleCurrency({ brainHome, identity = NIGHTLY_LABEL, moduleSource = path.dirname(fileURLToPath(import.meta.url)), runnerSource } = {}) {
+  const registration = readNightlyRegistration({ brainHome, identity });
+  if (!registration.ok) return { state: 'unregistered', why: registration.why };
+  const record = registration.record;
+  const registered = registeredModuleDigest(record);
+  if (!registered) return { state: 'unregistered', why: 'registration carries no module snapshot', fix: NIGHTLY_ENABLE_FIX };
+  const current = readModuleSet(moduleSource, record.mode === 'developer-suite').digest;
+  if (runnerSource && sha256(fs.readFileSync(runnerSource)) !== record.runnerSha256) return { state: 'runner-changed', registered, current, record, fix: NIGHTLY_ENABLE_FIX };
+  return registered === current ? { state: 'current', registered, current, record } : { state: 'stale', registered, current, record, fix: NIGHTLY_UPDATE_FIX };
+}
+
+/**
+ * After a successful --update: re-point a stale registration at the installed module set. Same identity, node,
+ * runner bytes, environment and targets, so only registration.json and a new update-modules-<digest> dir change
+ * and the LaunchAgent command stays exactly what it was; anything else is refused and left as it was.
+ */
+export const SCHEDULER_VISIBLE_FIELDS = Object.freeze(['identity', 'nodePath', 'runnerPath', 'runnerSha256', 'argv', 'environment', 'packageTarget', 'bundleTarget', 'mode']);
+export function refreshNightlyModules(options = {}) {
+  const currency = nightlyModuleCurrency(options);
+  if (currency.state !== 'stale') return currency;
+  const { record } = currency;
+  const plan = { brainHome: options.brainHome, identity: record.identity, source: record.runnerPath, nodePath: record.nodePath, packageTarget: record.packageTarget,
+    bundleTarget: record.bundleTarget, environment: record.environment ?? null, moduleSource: options.moduleSource, developerSuite: record.mode === 'developer-suite' };
+  // Compare the candidate BEFORE anything is written (reviewer proof 2026-10-22: an older registration without
+  // `environment` was rewritten with {} and only then refused). `build` is the dry-run of the one writer.
+  const candidate = (options.build || ((p) => installNightlyRunner({ ...p, dryRun: true })))(plan);
+  const differs = SCHEDULER_VISIBLE_FIELDS.filter((key) => JSON.stringify(candidate[key] ?? null) !== JSON.stringify(record[key] ?? null));
+  if (differs.length) return { ...currency, state: 'refused', reason: `refresh would change ${differs.join(', ')}; registration left as it was`, fix: NIGHTLY_ENABLE_FIX };
+  const refreshed = installNightlyRunner(plan);
+  return { ...currency, state: 'refreshed', registered: registeredModuleDigest(refreshed), fix: undefined };
+}
+
 export function readNightlyRegistration({ brainHome, identity = NIGHTLY_LABEL,
   recordPath = path.join(brainHome, 'scheduler', registrationName(identity)) }) {
   try {

package/plugin/scripts/ruflo-bin.mjs

@@ -245,7 +245,11 @@ export function rufloCwdFor(storePath, { root = rufloScratchRoot() } = {}) {
   return ensurePrivateDir(path.join(root, projectKey));
 }
 
-const RUFLO_CWD_ARTIFACTS = Object.freeze(['.swarm', '.claude', '.claude-flow', 'ruvector.db']);
+// node_modules / package.json / package-lock.json: ruflo's startup self-update runs `npm install @claude-flow/cli@X
+// --save-exact` in its cwd (ruflo v3 @claude-flow/cli dist/src/update/executor.js). Measured 2026-10-22: a 1.3 GB
+// install landed here. Every Brain spawn now sets CLAUDE_FLOW_AUTO_UPDATE=false (update/rate-limiter.js reads it);
+// these names are the backstop for a ruflo started without it.
+export const RUFLO_CWD_ARTIFACTS = Object.freeze(['.swarm', '.claude', '.claude-flow', 'ruvector.db', 'node_modules', 'package.json', 'package-lock.json']);
 const STALE_RUN_MS = 3_600_000;
 
 /**

package/plugin/scripts/ruflo-memory-hooks.mjs

@@ -48,7 +48,7 @@ export function projectStore(projectDir, { deadlineAt = Date.now() + 3000 } = {}
 export function rufloSpawnOptions(db, env = process.env) {
   let cwd;
   try { cwd = rufloRunDir(db, { root: rufloScratchRoot(env) }); } catch { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-ruflo-')); }
-  return { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' }, cleanup: () => { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later as a stale run- dir */ } } };
+  return { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false' }, cleanup: () => { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later as a stale run- dir */ } } };
 }
 
 /** One `ruflo memory <args>` call, bounded by the caller's deadline. Resolves, never rejects. */