ruvnet-brain 4.7.15 → 4.7.17

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

@@ -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/turn-outcome-capture.mjs

@@ -239,20 +239,18 @@ export function launchDetached(steps, { receipts, brainHome, projectDir, env = p
   return { launched: true, pid: child.pid };
 }
 
-function readTurnState(stateFile) {
-  try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')) || {}; } catch { return {}; }
-}
+const readTurnState = (stateFile) => { try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')) || {}; } catch { return {}; } };
+
+/** The newest store receipt for this exact key, while the receipt tail still holds it. */
+const storeReceipt = (receipts, key) => { try { return readTail(receipts, 128 * 1024).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } }).findLast((r) => r.kind === 'store' && r.key === key) || null; } catch { return null; } };
+const verifiedReceipt = (r) => r?.status === 0 && r.verified === true;
 
 function sameTurnSeen(stateFile, sessionKey, fingerprint, receipts) {
   const previous = readTurnState(stateFile)[sessionKey];
   if (previous?.fingerprint !== fingerprint) return false;
-  try {
-    const rows = readTail(receipts, 128 * 1024).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } });
-    const receipt = rows.findLast((r) => r.kind === 'store' && r.key === previous.key);
-    if (receipt) return receipt.status === 0 && receipt.verified === true;
-  } catch { /* queued worker has no receipt yet */ }
-  // An in-flight worker gets a bounded grace period; a killed/lost worker cannot consume the turn forever.
-  return Date.now() - previous.at < 2 * STEP_TIMEOUT_MS + 10_000;
+  const receipt = storeReceipt(receipts, previous.key);
+  // No receipt yet: an in-flight worker gets a bounded grace period; a killed/lost worker cannot consume the turn forever.
+  return receipt ? verifiedReceipt(receipt) : Date.now() - previous.at < 2 * STEP_TIMEOUT_MS + 10_000;
 }
 
 function markTurnQueued(stateFile, sessionKey, fingerprint, key) {
@@ -266,9 +264,8 @@ function markTurnQueued(stateFile, sessionKey, fingerprint, key) {
 }
 
 /**
- * Capture this turn's outcome (Stop) and/or queue distillation (SessionEnd, PreCompact).
- * Returns a plain report; `queued` means a worker request, never proof the store committed.
- * `skipped` / `distill.skipped` carry the reason whenever nothing is requested.
+ * Capture this turn's outcome (Stop) and/or start distillation (SessionEnd, PreCompact). Returns a plain report:
+ * `queued` means a request, never proof the store committed; `skipped` / `distill.skipped` carry the reason.
  */
 export function captureTurnOutcome({
   projectDir, event, payload = {}, host = 'claude',
@@ -322,10 +319,12 @@ export function captureTurnOutcome({
       const fingerprint = crypto.createHash('sha256').update(JSON.stringify([turn.finalText, turn.files])).digest('hex');
       const stateFile = path.join(brainHome, 'turn-capture', 'last-turn.json');
       const identity = crypto.createHash('sha256').update(`${host}:${db}:${sessionKey}`).digest('hex');
+      const key = `turn-${project}-${digest(`${identity}:${fingerprint}`).slice(0, 40)}`;
       if (sameTurnSeen(stateFile, identity, fingerprint, receipts)) report.skipped = 'same turn outcome already queued or verified';
+      // Proven at Stop already: SessionEnd/PreCompact must not re-send it (2026-10-19/20: each re-send was an "append rejected" row).
+      else if (verifiedReceipt(storeReceipt(receipts, key))) report.skipped = 'turn key already verified at an earlier boundary';
       else {
         const at = now();
-        const key = `turn-${project}-${digest(`${identity}:${fingerprint}`).slice(0, 40)}`;
         dedupe = { stateFile, identity, fingerprint, key };
         const value = buildTurnRecord({ turn, project, host, session: payload.session_id, at });
         steps.push({ ...binding, kind: 'store', ruflo, args: ['memory', 'store', '--key', key, '--value', value, '--namespace', TURN_NAMESPACE,
@@ -444,13 +443,14 @@ export function runSteps({ steps = [], receipts, event = '' } = {}, { run: suppl
       delete options.env.CLAUDE_FLOW_MEMORY_PATH;
       const r = run(invocation.executable, invocation.args, options);
       status = Number.isInteger(r.status) ? r.status : 1;
-      if (kind === 'store' && !verified && status === 0) verified = read({ ruflo, db, key, run, options }) === value;
-      if (verified) status = 0;
+      const duplicate = kind === 'store' && status !== 0 && /already exists/i.test(captureFailureReason(r, status)); // append-only refusal
+      if (kind === 'store' && (status === 0 || duplicate)) { verified = read({ ruflo, db, key, run, options }) === value; if (verified) status = 0; } // identical bytes = success
       if (kind === 'distill' && status === 0) {
         const match = /(?:^|\n)\s*skipped:\s*([^\n]+)/i.exec(String(r.stdout || '').replace(/\x1b\[[0-9;]*m/g, ''));
         if (match) skipped = redactText(match[1]).slice(0, 300);
       }
-      if (!verified && (r.error || status !== 0)) error = captureFailureReason(r, status);
+      if (!verified && duplicate) error = 'duplicate turn key holds different content';
+      else if (!verified && (r.error || status !== 0)) error = captureFailureReason(r, status);
       else if (kind === 'store' && !verified) { status = 1; error = 'exact turn key/content readback failed'; }
     } catch (e) { status = 1; error = redactText(e.message).slice(0, 300); }
     if (error) error = maskExcludedPaths(error, privacyPatterns, projectDir);

package/scripts/approved-runtime.mjs

@@ -46,6 +46,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { retryTransientResult } from './transient-gh.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -190,9 +191,12 @@ const semverDescending = (left, right) => {
   return b[0] - a[0] || b[1] - a[1] || b[2] - a[2];
 };
 
+// Every read here is a `gh` read of public release metadata or assets; a transient failure (rate limit, 5xx,
+// a reset mid-download of the ~555 MB archive) is retried, bounded, before it can fail the dispatcher, the
+// identity job or the publisher (scripts/transient-gh.mjs). A refused aggregate is an answer and is never retried.
 function defaultGh(args) {
-  const result = spawnSync(process.env.RUVNET_GH_COMMAND || 'gh', args,
-    { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 15 * 60_000 });
+  const result = retryTransientResult(() => spawnSync(process.env.RUVNET_GH_COMMAND || 'gh', args,
+    { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 15 * 60_000 }));
   if (result.error || result.status !== 0) {
     throw new Error(`gh ${args.slice(0, 3).join(' ')} failed: ${String(result.error?.message || result.stderr || `exit ${result.status}`).trim().slice(0, 400)}`);
   }

package/scripts/corpus-canary.mjs

@@ -47,6 +47,7 @@ import { addPrivateStore, resolveRuntime, resultFromRefreshReceipt, runInstaller
 import { CANARY_VERDICT_KIND, CORPUS_TAG_PATTERN, REQUIRED_CANARY_CHECKS } from './corpus-promotion.mjs';
 import { inventoryFootprint } from '../plugin/scripts/brain-footprint.mjs';
 import { eligibleRepositoryStanding } from '../plugin/scripts/coverage-integrity.mjs';
+import { TRANSIENT_HTTP, retryTransientAsync } from './transient-gh.mjs';
 
 export const PUBLIC_API = 'https://api.github.com';
 export const FRESHNESS_LIMIT_MS = 48 * 3_600_000;
@@ -151,9 +152,11 @@ export function storeFreshness({ after, before = null, now }) {
     const upstream = row.upstream?.sha || null;
     const built = row.artifact?.sourceCommit || null;
     if (!upstream || !built) continue;
+    // Named either way: a refresh that failed (upstream read, differs) or an upstream nobody could read tonight
+    // (pinned at the carried commit, `upstreamUnavailable`). Both are carried with a record the validator accepts.
+    if (row.kind === 'repository' && row.carry && eligibleRepositoryStanding(row) === 'shipped') { carried.push(row.artifact?.store || row.key); continue; }
     if (upstream !== built) {
-      if (row.kind === 'repository' && row.carry && eligibleRepositoryStanding(row) === 'shipped') carried.push(row.artifact?.store || row.key);
-      else stale.push(row.artifact?.store || row.key);
+      stale.push(row.artifact?.store || row.key);
       continue;
     }
     if (before && priorCommit.get(row.key) !== upstream) moved += 1;
@@ -285,15 +288,18 @@ function runLogged(command, args, { env, cwd, timeoutMs, log }) {
   return result;
 }
 
-/** Phase 1: the approved runtime, installed exactly as `npx ruvnet-brain@<version>` would. */
-export function installCustomer({ approvedVersion, work, home, log = () => {} }) {
+/**
+ * Phase 1: the approved runtime, installed exactly as `npx ruvnet-brain@<version>` would. The registry read is
+ * retried on a transient failure (bounded) so a registry blip reads as weather, never as "the customer refused".
+ */
+export async function installCustomer({ approvedVersion, work, home, log = () => {}, retryDelayMs = 30_000 }) {
   const env = customerEnv({ home, work });
   fs.mkdirSync(env.TMPDIR, { recursive: true });
   const prefix = path.join(work, 'npx');
   fs.mkdirSync(prefix, { recursive: true });
   const npm = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
-  runLogged(npm, ['install', '--prefix', prefix, '--no-audit', '--no-fund', '--no-save', `ruvnet-brain@${approvedVersion}`],
-    { env, cwd: prefix, timeoutMs: 600_000, log });
+  await retryTransientAsync(() => runLogged(npm, ['install', '--prefix', prefix, '--no-audit', '--no-fund', '--no-save', `ruvnet-brain@${approvedVersion}`],
+    { env, cwd: prefix, timeoutMs: 600_000, log }), { baseDelayMs: retryDelayMs, onRetry: ({ attempt }) => log(`--- npm install failed transiently (attempt ${attempt}); retrying`) });
   const installer = path.join(prefix, 'node_modules', 'ruvnet-brain', 'bin', 'install.mjs');
   const installed = readJson(path.join(prefix, 'node_modules', 'ruvnet-brain', 'package.json')).version;
   if (installed !== approvedVersion) throw new Error(`npm served ruvnet-brain ${installed}, not the approved ${approvedVersion}`);
@@ -316,8 +322,8 @@ function runUpdater({ kbDir, env, resultFile }) {
 }
 
 // An anonymous GitHub API read from a shared runner address is sometimes refused (403/429) or fails (5xx)
-// for a moment; one such blip must not fail the night. The same call is retried after a short wait.
-const TRANSIENT_HTTP = new Set([403, 429, 500, 502, 503, 504]);
+// for a moment; one such blip must not fail the night. The same call is retried after a short wait. The
+// status set is the pipeline's one definition (scripts/transient-gh.mjs TRANSIENT_HTTP), not a private copy.
 async function fetchJson(url, what, { retryDelayMs = 15_000, maxAttempts = 4 } = {}) {
   for (let attempt = 1; ; attempt += 1) {
     let status = null;

package/scripts/corpus-dispatch-decision.mjs

@@ -19,11 +19,31 @@
 // the new workflow passes (--approved-tag, --no-change-out, --stage-candidate, --promote-staged), so the nightly stands down rather than
 // let new workflow text drive old scripts.
 
+//
+// THE RETRY SLOT (2026-10-20). Measured on 38 nights: 24 failed, most on one transient blip, and nothing
+// retried until the next calendar day. The dispatcher now also fires at RETRY_CRON (11:17 UTC, four hours
+// after the night's first slot) and asks decideRetry(): re-dispatch ONLY when every corpus run of the
+// night so far ended `failed` (or reached no outcome), none is still running, none ended published /
+// no-change / superseded / canary-rejected (those are answers, not weather), and fewer than
+// MAX_CORPUS_RUNS_PER_NIGHT runs exist -- so one night gets at most one retry, and a deterministic
+// failure fails closed a second time rather than looping. The kill switch and the approved-runtime
+// resolution still run after it, exactly as on the first slot. Double publication is impossible by
+// construction: a failed run promoted nothing, every generation is content-addressed, and release.mjs
+// refuses a tag that already exists.
+
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 export const MIN_PIPELINE_VERSION = '4.3.38'; // sync-version-ignore: a fixed pipeline floor, not the current version
+/** The dispatcher's second schedule entry; corpus-nightly-dispatch.yml's `on.schedule` must carry exactly this line. */
+export const RETRY_CRON = '17 11 * * *';
+/** How far back the retry slot looks for the night's runs: past the 07:17 UTC first slot, never into yesterday. */
+export const RETRY_WINDOW_MS = 10 * 3_600_000;
+export const MAX_CORPUS_RUNS_PER_NIGHT = 2;
+// `unknown` (every job green, no outcome) is retried only when the run itself did NOT conclude success: a green
+// run that reached no outcome is a workflow defect the terminal-outcome job already fails loudly, not weather.
+const retryable = (run) => run.outcome === 'failed' || (run.outcome === 'unknown' && run.conclusion !== 'success');
 const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
 const HEX40 = /^[0-9a-f]{40}$/;
 const CODE_TAG = /^v\d+\.\d+\.\d+$/;
@@ -82,6 +102,21 @@ export function decide({ nightlyVar, resolution, minPipelineVersion = MIN_PIPELI
   return { verdict: 'arm', reason: `building the corpus at approved runtime ${tag} @ ${sourceSha}`, tag, version, sourceSha };
 }
 
+/**
+ * The retry slot's one decision. `runs`: the night's protected-release corpus runs so far
+ * (scripts/corpus-watchdog.mjs gatherCorpusRuns, each with `outcome` from classifyCorpusRun).
+ * Returns { verdict: 'retry' | 'stand-down', reason }.
+ */
+export function decideRetry({ runs = [], maxRuns = MAX_CORPUS_RUNS_PER_NIGHT } = {}) {
+  if (!runs.length) return { verdict: 'stand-down', reason: 'the first slot dispatched no corpus run tonight (it stood down or failed); the watchdog judges that, a retry would not' };
+  const running = runs.find((run) => run.outcome === 'in-progress');
+  if (running) return { verdict: 'stand-down', reason: `corpus run ${running.id} is still in progress` };
+  const settled = runs.find((run) => !retryable(run));
+  if (settled) return { verdict: 'stand-down', reason: `corpus run ${settled.id} ended ${settled.outcome}; that is the night's answer, not weather` };
+  if (runs.length >= maxRuns) return { verdict: 'stand-down', reason: `${runs.length} corpus run(s) already failed tonight; the bound is ${maxRuns} per night, so this is not retried again` };
+  return { verdict: 'retry', reason: `corpus run ${runs.map((run) => run.id).join(', ')} failed and nothing published; dispatching the night's one retry` };
+}
+
 /** approved-runtime.mjs --resolve's exit status + stdout (+ stderr, naming a refused release) -> a resolution. */
 export function resolutionFrom({ status, stdout, stderr = '' }) {
   if (String(status) === '3') return { status: 'not-yet-verified' };
@@ -107,12 +142,31 @@ const arg = (argv, name) => {
  * CLI: --nightly <value> --resolve-status <n|skipped> --release <file> [--resolve-stderr <file>]
  *      --github-output <file>. Exit 1 only on `fail`.
  *      --is-off <value>  prints true|false (lets the workflow skip the ~555 MB resolve when the switch is off)
+ *      --retry-slot --repo <owner/name> [--now ISO] --github-output <file>
+ *                        writes retry=true|false and retry_reason; exit 1 only when run history could not be read
  */
-export function main(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+export async function main(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
   if (argv.includes('--is-off')) {
     stdout.write(`${killSwitchOff(arg(argv, '--is-off'))}\n`);
     return 0;
   }
+  if (argv.includes('--retry-slot')) {
+    const { classifyCorpusRun, gatherCorpusRuns } = await import('./corpus-watchdog.mjs');
+    const now = arg(argv, '--now') ? Date.parse(arg(argv, '--now')) : Date.now();
+    const repo = arg(argv, '--repo') || process.env.GITHUB_REPOSITORY;
+    let decision;
+    try {
+      const runs = gatherCorpusRuns({ repo, since: now - RETRY_WINDOW_MS }).map((run) => ({ ...run, outcome: classifyCorpusRun(run) }));
+      decision = decideRetry({ runs });
+    } catch (error) {
+      stdout.write(`::error::corpus-nightly-dispatch retry slot could not read the night's runs: ${error.message}\n`);
+      return 1;
+    }
+    const githubOutput = arg(argv, '--github-output');
+    if (githubOutput) fs.appendFileSync(path.resolve(githubOutput), `retry=${decision.verdict === 'retry'}\nretry_reason=${decision.reason.replace(/\n/g, ' ')}\n`);
+    stdout.write(`::notice::corpus-nightly-dispatch retry slot ${decision.verdict}: ${decision.reason}\n`);
+    return 0;
+  }
   const nightlyVar = arg(argv, '--nightly') ?? '';
   const status = arg(argv, '--resolve-status');
   const releaseFile = arg(argv, '--release');
@@ -134,5 +188,5 @@ export function main(argv = process.argv.slice(2), { stdout = process.stdout } =
 }
 
 if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
-  process.exitCode = main();
+  main().then((code) => { process.exitCode = code; });
 }

package/scripts/corpus-next-seed.mjs

@@ -61,6 +61,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, bindCoverageToReceipt, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
+import { retryTransientResult } from './transient-gh.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX64 = /^[0-9a-f]{64}$/;
@@ -76,7 +77,10 @@ const REQUIRED_ASSETS = [ARCHIVE_ASSET, SIGNATURE_ASSET, RECEIPT_ASSET, RECALL_A
 /** ADR-0091 D4: judge at most this many of the newest generations, then use the committed bootstrap. */
 export const SEARCH_BOUND = 5;
 
-const defaultRun = (command, args, options) => spawnSync(command, args, { encoding: 'utf8', ...options });
+// Every `gh` call below is a read (release list, release view, small-asset download). A transient failure is
+// retried, bounded, before it is recorded as `indeterminate` (scripts/transient-gh.mjs): an unretried blip here
+// used to send the whole night back to the committed bootstrap seed -- a full rebuild dressed as a quiet night.
+const defaultRun = (command, args, options) => retryTransientResult(() => spawnSync(command, args, { encoding: 'utf8', ...options }));
 
 function ghJson(run, args) {
   const result = run('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });