ruvnet-brain 4.7.14 → 4.7.16

package/README.md

@@ -9,7 +9,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 ### Discover the stack. Read the source. Build with confidence.
 
-[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.14-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
+[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.16-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
 
 **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
 
@@ -255,7 +255,7 @@ uses the protected release workflow; a consumer update downloads an available ge
 does not rebuild upstream knowledge. Check `--doctor`, `SOURCE.json` and refresh receipts
 before treating an installation as current.
 
-The **4.6.0 published-corpus baseline** is **203 public stores · 164,402 public source chunks**.
+The **4.6.0 published-corpus baseline** is **203 public stores · 164,863 public source chunks**.
 Those are bundle census values, not a claim that every upstream repository is fresh today.
 Later corpus publication may advance the knowledge generation independently of code changes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.14",
+  "version": "4.7.16",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.7.14",
+  "version": "4.7.16",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.14",
+  "version": "4.7.16",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/scripts/coverage-integrity.mjs

@@ -293,11 +293,17 @@ export function eligibleRepositoryStanding(row) {
   if (status === 'CURRENT') return carry === undefined && failure === undefined ? 'shipped' : null;
   if (status === 'STALE' && carry && typeof carry === 'object' && failure === undefined) {
     const carried = String(carry.carriedSourceCommit || '').toLowerCase();
+    const upstream = String(row.upstream?.sha || '').toLowerCase();
+    // Two honest shapes. A refresh that FAILED: upstream was read, differs from the carried commit, and is named
+    // as missedUpstream. An upstream nobody could READ tonight (transient, source-coverage.mjs): the row is pinned
+    // at the carried commit, says `upstreamUnavailable`, and missedUpstream is null -- unknown, never invented.
+    const missed = String(carry.missedUpstream || '').toLowerCase();
+    const upstreamKnown = HEX40.test(missed) && missed === upstream && carried !== missed;
+    const upstreamUnread = carry.missedUpstream === null && row.upstreamUnavailable === true && row.upstreamUnavailableKind === 'transient'
+      && carry.reason === 'transient: upstream unreadable' && carried === upstream;
     const shipped = typeof carry.reason === 'string' && carry.reason.length > 0
       && HEX40.test(carried) && carried === String(row.artifact?.sourceCommit || '').toLowerCase()
-      && HEX40.test(String(carry.missedUpstream || '').toLowerCase())
-      && String(carry.missedUpstream).toLowerCase() === String(row.upstream?.sha || '').toLowerCase()
-      && carried !== String(carry.missedUpstream).toLowerCase()
+      && (upstreamKnown || upstreamUnread)
       && isAttemptCount(carry.attempts) && isIsoOrNull(carry.carriedCommittedAt)
       && row.artifact?.bytesVerified === true && row.artifact?.passagesPresent === true;
     return shipped ? 'shipped' : null;

package/plugin/scripts/developer-update.mjs

@@ -286,7 +286,7 @@ export async function synchronizePlugins(run, dryRun, notes, { home, prefix, sco
   if (JSON.stringify(flags) !== JSON.stringify(pluginFlags(writable, home))) throw Error('Codex plugin enablement changed');
   return { before, after, steps, provider };
 }
-function knowledge(run, dryRun, runId, { brainHome, root, node }) {
+export function knowledge(run, dryRun, runId, { brainHome, root, node }) {
   const kb = path.join(brainHome, 'kb'), updater = path.join(kb, 'forge-update.mjs');
   if (!exists(updater)) throw Error('existing Brain KB updater absent; fresh install refused');
   const file = path.join(brainHome, `nightly-suite-corpus-${runId}.json`);
@@ -299,7 +299,10 @@ function knowledge(run, dryRun, runId, { brainHome, root, node }) {
   }
   const before = check();
   if (before.currencyVerdict === 'CURRENT' || before.currencyVerdict === 'REFUSED') return { before, after: before, state: before.currencyVerdict === 'CURRENT' ? 'current' : 'ahead-preserved' };
-  if (before.currencyVerdict !== 'UPDATE_AVAILABLE') throw Error(`corpus currency unverified: ${before.currencyVerdict}`);
+  // UNKNOWN is what a tree installed from a code release reports (no corpus generation stamp): forge-update
+  // documents it as apply-allowed, exactly like UPDATE_AVAILABLE, and the check after the apply must reach
+  // CURRENT or REFUSED. Throwing here failed every scheduled night until someone ran --update by hand.
+  if (before.currencyVerdict !== 'UPDATE_AVAILABLE' && before.currencyVerdict !== 'UNKNOWN') throw Error(`corpus currency unverified: ${before.currencyVerdict}`);
   if (dryRun) return { before, state: 'update-available' };
   const installer = path.join(root, 'ruvnet-brain/bin/install.mjs');
   if (!exists(installer)) throw Error('existing Brain installer absent');

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'] });

package/scripts/corpus-reconcile.mjs

@@ -25,6 +25,7 @@ import { storeRoot } from '../kb/store-root.mjs';
 import { captureGistSources } from './gist-receipts.mjs';
 import { projectSourceStore, RUNTIME_LEDGER_KIND } from './rvf-generation.mjs';
 import { compareKnowledgeInputs, fromCoverage as knowledgeFromCoverage, fromSeed as knowledgeFromSeed } from './knowledge-input-digest.mjs';
+import { defaultBaseDelayMs } from './transient-gh.mjs';
 
 export { rebuildCorpusAggregates };
 
@@ -352,8 +353,10 @@ export async function acquireSealedGeneration({ maxAttempts = 3, assetsDir = nul
     const settled = await build(observation, storeOutcomes);
     const remaining = planReconciliation({ coverage: settled, ledger: currentLedger(), assetsDir })
       .filter((item) => !recorded(item.store));
+    // A repository row the shipped validator accepts WITH a carry -- a transiently unreadable source pinned at its
+    // seed commit (source-coverage.mjs) -- is resolved for this generation, exactly like a recorded store outcome.
     const unresolved = settled.rows.filter((row) => row.disposition === 'eligible' && row.status !== 'CURRENT'
-      && !(row.kind === 'repository' && recorded(row.artifact?.store)));
+      && !(row.kind === 'repository' && (recorded(row.artifact?.store) || (row.carry && eligibleRepositoryStanding(row) === 'shipped'))));
     attempts.push({ attempt, plan, ...reconciliation, ...pruning, ...aggregates,
       remainingArtifacts: remaining.length, unresolvedSources: unresolved.length });
     if (!remaining.length && !unresolved.length) {
@@ -635,11 +638,13 @@ export function dispositionForFailedStore({ assetsDir, ledger, item, attempts, r
 
 // Only a TRANSIENT failure is retried, exactly once, in a fresh directory: `<store>-retry1`. The first
 // attempt's directory is never reused -- a clone or a half-written worker output from the failed
-// attempt must not be mistaken for the retry's own (the pre-D5 path collided).
+// attempt must not be mistaken for the retry's own (the pre-D5 path collided). The retry waits
+// TRANSIENT_RETRY_DELAY_MS first: an immediate re-clone into the same reset connection learns nothing.
 export function workerRootFor(workspace, store, retry) {
   return path.join(workspace, 'workers', retry === 0 ? store : `${store}-retry${retry}`);
 }
 export const MAX_TRANSIENT_RETRIES = 1;
+export const TRANSIENT_RETRY_DELAY_MS = 30_000;
 
 export async function executeReconciliation({
   plan,
@@ -651,6 +656,8 @@ export async function executeReconciliation({
   signal,
   priorCoverage = null,
   log = (line) => console.log(line),
+  retryDelayMs = defaultBaseDelayMs(TRANSIENT_RETRY_DELAY_MS),
+  sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
 }) {
   if (!Array.isArray(plan) || !Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 10) {
     fail('reconciliation plan or worker concurrency is invalid');
@@ -750,8 +757,10 @@ export async function executeReconciliation({
         lastError = error;
         const retrying = isRetryable(error) && retry < MAX_TRANSIENT_RETRIES;
         log(`[corpus-reconcile] ${item.store}: attempt ${attempts} failed -- ${error.message}`
-          + (retrying ? '; retrying once in a fresh worker directory' : '; not retried'));
+          + (retrying ? `; retrying once in a fresh worker directory after ${retryDelayMs / 1000}s` : '; not retried'));
         if (!retrying) break;
+        await sleep(retryDelayMs);
+        if (controller.signal.aborted) throw abortError(controller.signal);
       }
     }
     return { ok: false, attempts, error: lastError };
@@ -871,7 +880,33 @@ async function observeSourceOnly({ owner, assetsDir }) {
   const externalFile = path.join(assets, 'external-sources.json');
   const policy = fs.existsSync(externalFile) ? readJson(externalFile, 'external source policy') : { sources: [] };
   if (!Array.isArray(policy.sources)) fail('external source policy has no sources array');
-  return observeSourceUniverse({ owner, externalSources: policy.sources });
+  const ledgerFile = path.join(assets, 'RVF-GENERATIONS.json');
+  const ledger = fs.existsSync(ledgerFile) ? readJson(ledgerFile, 'RVF generation ledger') : { stores: {} };
+  return observeSourceUniverse({ owner, externalSources: policy.sources,
+    carriedCommits: transientCarryCommits({ ledger, priorCoverage: readPriorCoverage(assets) }) });
+}
+
+/**
+ * The seed's own commits, per store: what an external source unreadable tonight is pinned at (one night, STALE
+ * with a carry) instead of failing the whole observation. Read from the seed ledger, never invented -- and a store
+ * the SEED's sealed coverage already shows carried this way is left out, so the second consecutive night fails
+ * for that source exactly as before rather than carrying it forever.
+ */
+export function transientCarryCommits({ ledger, priorCoverage = null }) {
+  // No sealed coverage to read history from (the bootstrap lineage, or an invalid sidecar) = no carry at all:
+  // the allowance exists only where the previous night can prove it was not already spent.
+  if (!Array.isArray(priorCoverage?.rows)) return {};
+  // ANY carried seed row spends it -- a failed refresh last night and an unreadable upstream tonight must not
+  // alternate forever either.
+  const alreadyCarried = new Set(priorCoverage.rows
+    .filter((row) => row?.kind === 'repository' && row.carry)
+    .map((row) => String(row.artifact?.store || '').toLowerCase()));
+  return Object.fromEntries(Object.entries(ledger?.stores || {})
+    .filter(([store, row]) => HEX40.test(String(row?.sourceCommit || '').toLowerCase()) && !alreadyCarried.has(store.toLowerCase()))
+    .map(([store, row]) => {
+      const sourceCommit = String(row.sourceCommit).toLowerCase();
+      return [store.toLowerCase(), { sourceCommit, committedAt: carriedCommittedAt({ priorCoverage, store, sourceCommit }) }];
+    }));
 }
 
 export async function acquireCorpusGeneration({ owner = 'ruvnet', assetsDir, workspaceDir,

package/scripts/corpus-watchdog.mjs

@@ -22,6 +22,10 @@
 //   WARNING  a superseded or degraded night, a stand-down tonight, an unknown outcome, a long run
 //   GREEN    none of the above
 //
+// THE FIRST LINE IS THE NIGHT'S VERDICT (2026-10-20, summarizeNight): what the night did -- published,
+// no-change, degraded with the stores named, failed with the stage named, superseded, canary-rejected, still
+// running, stood down -- in Eastern time, result first, so the owner never learns of a break from a page.
+//
 // Exit code is the contract (same as scripts/github-health-watch.mjs): 0 = GREEN or WARNING,
 // 1 = RED or the evidence could not be gathered. corpus-watchdog.yml runs on a genuine `schedule:`,
 // so its red conclusion fires ntfy-alerts.yml's workflow_run listener — no secret needed here.
@@ -43,6 +47,7 @@ import { CODE_TAG_PATTERN, isCorpusReleaseTag } from './release-channel-kind.mjs
 import { AGGREGATE_ASSET, SIGNING_PUBLIC_KEY_FILE } from './approved-runtime.mjs';
 import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 import { parseCorpusGeneration } from './corpus-promotion.mjs';
+import { retryTransientResult } from './transient-gh.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const RED = 'RED';
@@ -255,7 +260,9 @@ export function judgeCorpusHealth(input, now) {
 // ── Gathering (read-only gh). Everything above is pure; everything below talks to GitHub. ──────────
 
 function defaultGh(args) {
-  const result = spawnSync(process.env.RUVNET_GH_COMMAND || 'gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 5 * 60_000 });
+  // A transient gh failure is retried, bounded (scripts/transient-gh.mjs); the judge must not page RED on weather.
+  const result = retryTransientResult(() => spawnSync(process.env.RUVNET_GH_COMMAND || 'gh', args,
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 5 * 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, 300)}`);
   }
@@ -320,17 +327,25 @@ function corpusRunEvidence({ gh, repo, run, scratch }) {
   }
 }
 
+/**
+ * The protected-release corpus runs created since `since` (ms), each with its outcome evidence. Shared with the
+ * dispatcher's retry slot (scripts/corpus-dispatch-decision.mjs --retry-slot), so both read one definition of
+ * "tonight's runs" and one classifier.
+ */
+export function gatherCorpusRuns({ repo, since, gh = defaultGh, scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-watchdog-')) }) {
+  return JSON.parse(gh(['run', 'list', '--repo', repo, '--workflow', 'protected-release.yml', '--limit', '60',
+    '--json', 'databaseId,attempt,displayTitle,status,conclusion,createdAt,updatedAt']))
+    .filter((run) => CORPUS_RUN_TITLE.test(String(run.displayTitle || '')) && (ms(run.createdAt) ?? 0) >= since)
+    .map((run) => ({ id: run.databaseId, title: run.displayTitle, status: run.status, conclusion: run.conclusion,
+      createdAt: run.createdAt, updatedAt: run.updatedAt, ...corpusRunEvidence({ gh, repo, run, scratch }) }));
+}
+
 export async function gatherCorpusHealthInput({ repo, now, gh = defaultGh, root = ROOT, scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-watchdog-')) }) {
   const at = now.getTime();
-  const recent = (iso) => (ms(iso) ?? 0) >= at - 3 * 24 * HOUR;
   const dispatcherRuns = JSON.parse(gh(['run', 'list', '--repo', repo, '--workflow', 'corpus-nightly-dispatch.yml', '--limit', '30',
     '--json', 'databaseId,attempt,event,status,conclusion,createdAt,updatedAt']))
     .map((run) => ({ id: run.databaseId, attempt: run.attempt, event: run.event, status: run.status, conclusion: run.conclusion, createdAt: run.createdAt }));
-  const corpusRuns = JSON.parse(gh(['run', 'list', '--repo', repo, '--workflow', 'protected-release.yml', '--limit', '60',
-    '--json', 'databaseId,attempt,displayTitle,status,conclusion,createdAt,updatedAt']))
-    .filter((run) => CORPUS_RUN_TITLE.test(String(run.displayTitle || '')) && recent(run.createdAt))
-    .map((run) => ({ id: run.databaseId, title: run.displayTitle, status: run.status, conclusion: run.conclusion,
-      createdAt: run.createdAt, updatedAt: run.updatedAt, ...corpusRunEvidence({ gh, repo, run, scratch }) }));
+  const corpusRuns = gatherCorpusRuns({ repo, since: at - 3 * 24 * HOUR, gh, scratch });
   const releases = JSON.parse(gh(['release', 'list', '--repo', repo, '--limit', '100', '--json', 'tagName,publishedAt,isDraft,isPrerelease']));
   // PROMOTED only: a staged candidate (and a bootstrap seed) is a prerelease no customer receives.
   const corpusReleases = releases.filter((row) => !row.isDraft && !row.isPrerelease && isCorpusReleaseTag(row.tagName))
@@ -364,8 +379,72 @@ export async function gatherCorpusHealthInput({ repo, now, gh = defaultGh, root
   return { corpusReleases, corpusRuns, dispatcherRuns, codeRelease, deferral, latestRelease };
 }
 
+/** A time the owner reads: local Eastern, 12-hour, named zone -- never UTC or "Z". */
+export function formatEastern(when) {
+  const t = when instanceof Date ? when.getTime() : ms(when);
+  if (t === null || !Number.isFinite(t)) return 'an unknown time';
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', month: 'short', day: 'numeric',
+    hour: 'numeric', minute: '2-digit', hour12: true }).formatToParts(new Date(t)).map((part) => [part.type, part.value]));
+  return `${parts.hour}:${parts.minute} ${parts.dayPeriod.toLowerCase().replace(/^(a|p)m$/, '$1.m.')} ET ${parts.month} ${parts.day}`;
+}
+
+/** The job the night died in, named as the owner knows the stage, from the terminal outcome record or the job list. */
+const STAGE_NAMES = { identity: 'authorize (corpus-identity)', prepare: 'prepare/seal (seal-exact-corpus-candidate)',
+  authorize: 'authenticate (corpus-authorize)', publish: 'publisher (corpus-publish)', canary: 'customer canary', promote: 'promote' };
+const JOB_NAMES = { 'authorize-corpus-generation': 'identity', 'seal-exact-corpus-candidate': 'prepare', 'authenticate-corpus-preparation-provenance': 'authorize',
+  'protected-corpus-publisher': 'publish', 'customer-canary': 'canary', 'promote-canaried-corpus': 'promote' };
+export function failedStage(run) {
+  const recorded = Object.entries(run?.outcomeRecord?.jobs || {}).find(([, result]) => result === 'failure')?.[0];
+  const listed = (run?.jobs || []).find((job) => job.conclusion === 'failure' && JOB_NAMES[job.name]);
+  const stage = recorded || (listed ? JOB_NAMES[listed.name] : null);
+  return stage ? STAGE_NAMES[stage] || stage : `an unnamed job (conclusion ${run?.conclusion || 'unknown'})`;
+}
+
+/**
+ * THE ONE LINE the owner reads first: what the night did, result first, in Eastern time. `input` is
+ * gatherCorpusHealthInput's; the night is the newest corpus run of the last 24h and every retry of it.
+ * Never learned from a page: the watchdog writes this before ntfy ever fires.
+ */
+export function summarizeNight(input, now) {
+  const at = now instanceof Date ? now.getTime() : Number(now);
+  const inWindow = (iso) => { const t = ms(iso); return t !== null && t <= at && at - t <= TONIGHT_WINDOW_MS; };
+  const runs = (input?.corpusRuns || []).filter((run) => inWindow(run.createdAt))
+    .map((run) => ({ ...run, outcome: run.outcome ?? classifyCorpusRun(run) })).sort((a, b) => ms(b.createdAt) - ms(a.createdAt));
+  const dispatcher = (input?.dispatcherRuns || []).filter((d) => inWindow(d.createdAt)).sort((a, b) => ms(b.createdAt) - ms(a.createdAt))[0];
+  const latest = input?.latestRelease;
+  const attempts = runs.length > 1 ? ` (attempt ${runs.length} of the night; ${runs.length - 1} retried)` : '';
+  const keep = latest ? `customers keep ${latest.tag} (${hours(Math.max(0, at - (ms(latest.generation || latest.publishedAt) ?? at)))} old)` : 'no promoted generation is observed';
+  if (!runs.length) {
+    if (!dispatcher) return { outcome: 'no-run', line: `night: no corpus run in the last 24h (no dispatcher run either); ${keep}` };
+    if (dispatcher.status !== 'completed') return { outcome: 'dispatching', line: `night: dispatcher run ${dispatcher.id} is ${dispatcher.status} (started ${formatEastern(dispatcher.createdAt)})` };
+    if (dispatcher.conclusion !== 'success') return { outcome: 'dispatcher-failed', line: `night: dispatcher run ${dispatcher.id} concluded ${dispatcher.conclusion} at ${formatEastern(dispatcher.createdAt)}, nothing was dispatched; ${keep}` };
+    return { outcome: 'stood-down', line: `night: stood down at ${formatEastern(dispatcher.createdAt)} (CORPUS_NIGHTLY off, or no install-verified runtime); ${keep}` };
+  }
+  const [run] = runs;
+  const when = formatEastern(run.updatedAt || run.createdAt);
+  const degraded = input?.deferral?.observable && input.deferral.degraded && latest && input.deferral.newestTag === latest.tag
+    && (input.deferral.degraded.carried.length || input.deferral.degraded.missing.length) ? input.deferral.degraded : null;
+  switch (run.outcome) {
+    case 'published': {
+      const tag = latest && (ms(latest.publishedAt) ?? 0) >= (ms(run.createdAt) ?? 0) ? latest.tag : 'a new generation';
+      if (degraded) {
+        return { outcome: 'degraded', line: `night: degraded -- published ${tag} at ${when}${attempts} with ${degraded.carried.length} carried `
+          + `(${degraded.carried.join(', ') || 'none'}) and ${degraded.missing.length} missing (${degraded.missing.join(', ') || 'none'}), each named in CORPUS-COVERAGE.json` };
+      }
+      return { outcome: 'published', line: `night: published ${tag} at ${when}${attempts}` };
+    }
+    case 'no-change': return { outcome: 'no-change', line: `night: no-change at ${when}${attempts} -- every knowledge input equals the promoted generation; ${keep}` };
+    case 'superseded': return { outcome: 'superseded', line: `night: superseded at ${when} -- a newer code release landed; the next night builds at it; ${keep}` };
+    case 'canary-rejected': return { outcome: 'canary-rejected', line: `night: canary-rejected at ${when}${attempts} -- a clean customer install could not apply the candidate (GLOBAL: not retried); ${keep}` };
+    case 'in-progress': return { outcome: 'in-progress', line: `night: run ${run.id} still in progress, started ${formatEastern(run.createdAt)}${attempts}` };
+    case 'failed': return { outcome: 'failed', line: `night: failed in ${failedStage(run)} at ${when}${attempts}; ${keep}` };
+    default: return { outcome: 'unknown', line: `night: run ${run.id} succeeded at ${when} but reached no outcome${attempts}; ${keep}` };
+  }
+}
+
 export function renderReport(result, now) {
-  const lines = [`corpus-watchdog ${result.verdict} at ${now.toISOString()}`];
+  const lines = [`corpus-watchdog ${result.verdict} -- ${result.night?.line || `judged ${formatEastern(now)}`}`,
+    `  judged ${formatEastern(now)} (${now.toISOString()})`];
   for (const f of result.findings) lines.push(`  [${f.level}] ${f.check}: ${f.detail}`);
   return `${lines.join('\n')}\n`;
 }
@@ -380,7 +459,8 @@ async function main(argv = process.argv.slice(2)) {
   }
   let result;
   try {
-    result = judgeCorpusHealth(await gatherCorpusHealthInput({ repo, now }), now);
+    const input = await gatherCorpusHealthInput({ repo, now });
+    result = { ...judgeCorpusHealth(input, now), night: summarizeNight(input, now) };
   } catch (error) {
     // Could not observe = could not prove health. Absence of evidence is failure.
     process.stderr.write(`corpus-watchdog RED: evidence could not be gathered: ${error.message}\n`);

package/scripts/gist-receipts.mjs

@@ -34,6 +34,7 @@ import { canonicalJson, digest, validateGistAggregateReceipt } from './coverage-
 import { promoteArtifactSet } from '../kb/incremental-refresh.mjs';
 import { writeRvfGeneration } from './rvf-generation.mjs';
 import { fetchGistGitSnapshot } from './gist-git-transport.mjs';
+import { isTransientText, retryTransientAsync } from './transient-gh.mjs';
 
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.rst']);
@@ -402,9 +403,15 @@ function reusableCachedGist(cached, stub) {
   return 'reuse';
 }
 
+// The Git snapshot is one `ls-remote` + one bare clone per gist against gist.github.com. A transient transport
+// failure (reset, timeout, "could not read Username", or the gist moving mid-capture) is retried, bounded, so
+// one blip on one of ~180 gists cannot fail the aggregate and with it the night. A gist that is gone
+// ("repository not found") is an answer and is thrown at once.
+const transientGistSnapshot = (error) => isTransientText(error?.message) || /moved while Git snapshot was captured/.test(String(error?.message || ''));
+
 export async function captureGistSources({ observation, cache = null, fetchDetail = null,
   fetchRaw = defaultFetchRaw, fetchGitSnapshot = fetchGistGitSnapshot, signal,
-  now = () => new Date().toISOString() } = {}) {
+  now = () => new Date().toISOString(), snapshotRetryDelayMs = 15_000 } = {}) {
   const stubs = observation?.gists?.rows;
   if (!Array.isArray(stubs) || stubs.some(({ id }) => !HEX_GIST.test(String(id || '')))
     || new Set(stubs.map(({ id }) => id)).size !== stubs.length) {
@@ -420,7 +427,8 @@ export async function captureGistSources({ observation, cache = null, fetchDetai
       // The production/no-key route never spends one REST detail request per gist and never trusts
       // a body-free cache or timestamps as content identity. A full bare clone gives one immutable
       // Git commit/tree; every observed raw_url's blob identity must match its HEAD file bytes.
-      const snapshot = await fetchGitSnapshot({ owner: observation.owner, stub, signal });
+      const snapshot = await retryTransientAsync(() => fetchGitSnapshot({ owner: observation.owner, stub, signal }),
+        { isTransient: transientGistSnapshot, baseDelayMs: snapshotRetryDelayMs });
       const files = [];
       for (const source of snapshot.files) {
         const filename = source.filename;

package/scripts/release.mjs

@@ -71,6 +71,7 @@ import {
 import { bindCoverageToReceipt, writeCoverageAssets } from './corpus-coverage-sidecar.mjs';
 import { describeDegraded } from './corpus-store-failure.mjs';
 import { assertNoNewerCorpusGeneration } from './code-release-corpus.mjs';
+import { retryingGh } from './transient-gh.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const PUBLISH = process.argv.includes('--publish');
@@ -141,11 +142,17 @@ const compareCodeTags = (left, right) => {
   return Math.sign(a[0] - b[0] || a[1] - b[1] || a[2] - b[2]);
 };
 
-/** The one gh seam both corpus entry points use (RUVNET_GH_COMMAND / RUVNET_GH_SCRIPT for tests). */
+/**
+ * The one gh seam both corpus entry points use (RUVNET_GH_COMMAND / RUVNET_GH_SCRIPT for tests). Reads and the
+ * idempotent `release edit` retry a transient failure, bounded (scripts/transient-gh.mjs): on 2026-09-29 the
+ * night was red on "cannot confirm the promoted corpus release" -- one `release view` that failed right after
+ * the write had succeeded. `release create` runs exactly once; the absence proof above it is what makes a
+ * repeat safe to refuse.
+ */
 function corpusGh(env, run) {
-  const ghCommand = env.RUVNET_GH_COMMAND || 'gh';
-  const ghPrefix = env.RUVNET_GH_SCRIPT ? [env.RUVNET_GH_SCRIPT] : [];
-  const gh = (args) => run(ghCommand, [...ghPrefix, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  const gh = retryingGh({ run, command: env.RUVNET_GH_COMMAND || 'gh', prefix: env.RUVNET_GH_SCRIPT ? [env.RUVNET_GH_SCRIPT] : [],
+    options: { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+    onRetry: ({ attempt, args, delayMs }) => console.error(`[corpus-seed] gh ${args.slice(0, 2).join(' ')} failed transiently (attempt ${attempt}); retrying in ${delayMs / 1000}s`) });
   const ghJson = (args, label) => {
     const result = gh(args);
     if (result.error || result.status !== 0) {

package/scripts/source-coverage.mjs

@@ -9,6 +9,7 @@ import { readRvfGenerations, sha256File } from './rvf-generation.mjs';
 import { canonicalJson, coverageGenerationFor, digest, validateGistAggregateReceipt } from './coverage-integrity.mjs';
 import { repositoryNames } from '../kb/card-lane.mjs';
 import { rootNeverMaterialized, storeRoot } from '../kb/store-root.mjs';
+import { isTransientText, retryTransient, sleepSync } from './transient-gh.mjs';
 
 export { canonicalJson, digest } from './coverage-integrity.mjs';
 
@@ -52,6 +53,11 @@ function runGh(args) {
   return result.stdout;
 }
 
+// Every observation read below goes through this: a transient failure (rate limit, 5xx, a reset) is retried,
+// bounded, before it can fail the night (scripts/transient-gh.mjs). Applied around the INJECTED `gh`, not
+// inside runGh, so the fault-injection suite exercises the same retry the nightly runs.
+const retryingRead = (gh, sleep) => (args) => retryTransient(() => gh(args), { sleep });
+
 // A fork's disposition depends on how many commits it carries that its upstream does not. The
 // compare is pinned to the two heads THIS observation recorded (never to branch names, which move),
 // and is run against the upstream repository in GitHub's documented cross-fork form
@@ -80,7 +86,8 @@ function observeForkDelta(owner, node, gh) {
   };
 }
 
-export function observeRepositories(owner, { gh = runGh } = {}) {
+export function observeRepositories(owner, { gh: rawGh = runGh, sleep = sleepSync } = {}) {
+  const gh = retryingRead(rawGh, sleep);
   const rows = [];
   const pages = [];
   let cursor = '';
@@ -103,10 +110,11 @@ export function observeRepositories(owner, { gh = runGh } = {}) {
   return { rows: withDeltas, expected, pages };
 }
 
-// The row an external source reports once its upstream is gone: exactly what was last observed, so the
-// stored content classifies CURRENT, nothing is re-ingested, and the row says plainly it is no longer live.
-function goneExternalRow(source) {
-  const gone = source.ifGone;
+// The row an external source reports when its upstream cannot be read: exactly what was last observed (or last
+// ingested), so the stored content classifies CURRENT, nothing is re-ingested, and the row says plainly why.
+// `gone` is the policy's ifGone entry (404/410); for a source unreadable for a moment it is the seed ledger's
+// own commit, with `reason` naming the failure.
+function unavailableExternalRow(source, gone, reason) {
   if (!/^[0-9a-f]{40}$/i.test(String(gone.sourceCommit || ''))) {
     throw new Error(`external source ${source.repository}: ifGone.sourceCommit must be the 40-hex commit last ingested`);
   }
@@ -114,12 +122,27 @@ function goneExternalRow(source) {
     name: source.repository.split('/')[1], fullName: source.repository, storeName: source.store,
     url: `https://github.com/${source.repository}`, description: gone.description ?? null, homepageUrl: null,
     isFork: false, upstreamIsFork: false, isArchived: false, isDisabled: false,
-    updatedAt: gone.updatedAt ?? null, pushedAt: gone.pushedAt ?? null, upstreamUnavailable: true,
+    updatedAt: gone.updatedAt ?? null, pushedAt: gone.pushedAt ?? null, upstreamUnavailable: true, upstreamUnavailableReason: reason,
     defaultBranchRef: { name: gone.defaultBranch || 'HEAD', target: { oid: gone.sourceCommit, committedDate: gone.committedAt ?? null } },
   };
 }
 
-export function observeExternalRepositories(sources, { gh = runGh } = {}) {
+/** The one reason a transient carry records; scripts/corpus-reconcile.mjs refuses a second consecutive one by it. */
+export const TRANSIENT_UNREADABLE_REASON = 'was unreadable this observation (transient failure after the bounded retry); it is read again next night';
+/** The carry record a transiently unreadable source ships: STALE, not CURRENT, and counted toward the degraded bound. */
+export const TRANSIENT_CARRY_REASON = 'transient: upstream unreadable';
+
+/**
+ * `carriedCommits`: { <store>: { sourceCommit, committedAt } } from the seed's own generation ledger, already stripped
+ * of any store the seed's coverage shows was ALREADY carried this way (corpus-reconcile.mjs transientCarryCommits),
+ * so the same source is never carried two nights running. A source whose read still fails TRANSIENTLY after the
+ * bounded retry (rate limit, 5xx, a reset; measured 2026-09-26) is pinned at that commit for ONE night: its row
+ * classifies STALE with a `carry` record (nobody read upstream tonight, so it is not called current), it counts
+ * toward max(3, 5% of eligible) with every other carried store, and the next night reads it again. Without a prior
+ * commit there is nothing honest to carry, and the observation fails.
+ */
+export function observeExternalRepositories(sources, { gh: rawGh = runGh, sleep = sleepSync, carriedCommits = null } = {}) {
+  const gh = retryingRead(rawGh, sleep);
   const rows = [];
   const pages = [];
   for (const source of sources) {
@@ -134,13 +157,28 @@ export function observeExternalRepositories(sources, { gh = runGh } = {}) {
         ? JSON.parse(gh(['api', `repos/${source.repository}/commits/${repo.default_branch}`]))
         : null;
     } catch (error) {
-      // An upstream that GitHub reports gone (404/410) must not stop every night for every customer.
-      // Only a source whose policy entry records `ifGone` (the commit it was last ingested at) may be
-      // carried; anything else -- 403, rate limit, a mistyped repository -- still fails the observation.
-      if (!source.ifGone || !/\(HTTP (404|410)\)/.test(String(error.message))) throw error;
-      process.stderr.write(`[source-coverage] external source ${source.repository} is gone upstream; carrying the last ingested content (${source.ifGone.sourceCommit})\n`);
-      rows.push(goneExternalRow(source));
-      pages.push({ repository: source.repository, responseDigest: digest({ gone: source.repository, ifGone: source.ifGone }), count: 1, terminal: true });
+      // An upstream that GitHub reports gone (404/410) must not stop every night for every customer: a source
+      // whose policy entry records `ifGone` (the commit it was last ingested at) is carried there. A source that
+      // is merely unreadable tonight (still transient after the retry) is carried at the seed's own commit when
+      // it has one. Anything else -- a bare 403, a mistyped repository, no prior bytes -- still fails the observation.
+      const message = String(error.message);
+      const gone = source.ifGone && /\(HTTP (404|410)\)/.test(message);
+      const prior = carriedCommits?.[String(source.store).toLowerCase()];
+      const carried = String(prior?.sourceCommit ?? prior ?? '').toLowerCase();
+      const unreadable = !gone && isTransientText(message) && /^[0-9a-f]{40}$/.test(carried);
+      if (!gone && !unreadable) throw error;
+      // FIXED shapes, never the error text or a timestamp: the observation digest feeds the no-change decision,
+      // so a night that carried one unreadable source and saw nothing else move must still read as unchanged.
+      const kind = gone ? 'gone' : 'transient';
+      const reason = gone ? 'is no longer reachable (HTTP 404/410)' : TRANSIENT_UNREADABLE_REASON;
+      // committedAt comes from the seed's own coverage row (corpus-reconcile.mjs carriedCommittedAt), so the customer's
+      // "oldest carried" line dates the pinned commit instead of showing an unknown date.
+      const at = gone ? source.ifGone : { sourceCommit: carried, committedAt: prior?.committedAt ?? null };
+      process.stderr.write(`[source-coverage] external source ${source.repository} ${reason}; carrying the last ingested content (${at.sourceCommit})`
+        + `${gone ? '' : ` -- ${message.replace(/\s+/g, ' ').trim().slice(0, 200)}`}\n`);
+      rows.push({ ...unavailableExternalRow(source, at, reason), upstreamUnavailableKind: kind });
+      pages.push({ repository: source.repository, responseDigest: digest(gone ? { gone: source.repository, ifGone: source.ifGone }
+        : { unavailable: source.repository, kind, at: carried }), count: 1, terminal: true });
       continue;
     }
     const row = {
@@ -164,9 +202,11 @@ export function observeSourceUniverse({
   externalSources = [],
   gh = runGh,
   observedAt = new Date().toISOString(),
+  sleep = sleepSync,
+  carriedCommits = null,
 } = {}) {
-  const primary = observeRepositories(owner, { gh });
-  const external = observeExternalRepositories(externalSources, { gh });
+  const primary = observeRepositories(owner, { gh, sleep });
+  const external = observeExternalRepositories(externalSources, { gh, sleep, carriedCommits });
   const repositoryRows = canonicalRepositoryRows([...primary.rows, ...external.rows]);
   const repositories = sourceSetObservation(repositoryRows, primary.expected + external.expected);
   const repositoryKeys = new Set();
@@ -179,7 +219,7 @@ export function observeSourceUniverse({
     repositoryKeys.add(repositoryKey);
     storeKeys.add(storeKey);
   }
-  const observedGists = observeGists(owner, { gh });
+  const observedGists = observeGists(owner, { gh, sleep });
   const gists = sourceSetObservation(canonicalGistRows(observedGists.rows), observedGists.expected);
   return canonicalSourceObservation({
     schemaVersion: 1,
@@ -222,6 +262,8 @@ export function canonicalRepositoryRows(rows = []) {
     isArchived: repo?.isArchived === true,
     isDisabled: repo?.isDisabled === true,
     ...(repo?.upstreamUnavailable === true ? { upstreamUnavailable: true } : {}),
+    ...(repo?.upstreamUnavailable === true && repo?.upstreamUnavailableReason ? { upstreamUnavailableReason: String(repo.upstreamUnavailableReason) } : {}),
+    ...(repo?.upstreamUnavailable === true && repo?.upstreamUnavailableKind ? { upstreamUnavailableKind: String(repo.upstreamUnavailableKind) } : {}),
     diskUsage: repo?.diskUsage,
     updatedAt: repo?.updatedAt ?? null,
     pushedAt: repo?.pushedAt ?? null,
@@ -325,7 +367,11 @@ function listGistsUnauthenticated(owner, curl) {
   return pages;
 }
 
-export function observeGists(owner, { gh = runGh, curl = runCurl } = {}) {
+export function observeGists(owner, { gh: rawGh = runGh, curl: rawCurl = runCurl, sleep = sleepSync } = {}) {
+  // A rate limit on either channel (measured 2026-09-26: the gist list) is retried, bounded, before the
+  // integration-token 403 is allowed to fall back to the anonymous list, which is itself rate-limited.
+  const gh = retryingRead(rawGh, sleep);
+  const curl = retryingRead(rawCurl, sleep);
   let pages;
   try {
     const raw = gh(['api', `users/${owner}/gists?per_page=100`, '--paginate', '--slurp']);
@@ -414,8 +460,19 @@ export function classifyRepository(repo, evidence, exclusion = null, outcome = n
     status = 'FAILED';
     reasons.push(outcome.integrity);
   }
-  if (repo.upstreamUnavailable === true) reasons.push(`upstream ${repo.fullName} is no longer reachable (HTTP 404/410); serving the content last ingested at ${upstreamSha}`);
+  if (repo.upstreamUnavailable === true) {
+    reasons.push(`upstream ${repo.fullName} ${repo.upstreamUnavailableReason || 'is no longer reachable (HTTP 404/410)'}; serving the content last ingested at ${upstreamSha}`);
+  }
   const record = {};
+  // A source nobody could read tonight is never CURRENT: its bytes are pinned at the last commit the seed carried,
+  // and the row ships a carry record (missedUpstream null -- the upstream head is unknown, not merely different)
+  // that eligibleRepositoryStanding accepts only together with upstreamUnavailable. A `gone` source stays CURRENT:
+  // its upstream was READ and is final.
+  if (disposed && repo.upstreamUnavailableKind === 'transient' && status === 'CURRENT') {
+    status = 'STALE';
+    record.carry = { reason: TRANSIENT_CARRY_REASON, carriedSourceCommit: upstreamSha, missedUpstream: null,
+      attempts: 1, carriedCommittedAt: repo.defaultBranchRef?.target?.committedDate || null };
+  }
   if (disposed && outcome?.carry && status === 'STALE') record.carry = { ...outcome.carry };
   if (disposed && outcome?.failure && status === 'MISSING') record.failure = { ...outcome.failure };
   return {
@@ -428,6 +485,7 @@ export function classifyRepository(repo, evidence, exclusion = null, outcome = n
     disposition,
     archived: repo.isArchived === true,
     ...(repo.upstreamUnavailable === true ? { upstreamUnavailable: true } : {}),
+    ...(repo.upstreamUnavailable === true && repo.upstreamUnavailableKind ? { upstreamUnavailableKind: repo.upstreamUnavailableKind } : {}),
     ...(repo.forkDelta ? { forkDelta: { ...repo.forkDelta } } : {}),
     upstream: { sha: upstreamSha, committedAt: repo.defaultBranchRef?.target?.committedDate || null,
       pushedAt: repo.pushedAt, updatedAt: repo.updatedAt },

package/scripts/transient-gh.mjs

@@ -0,0 +1,150 @@
+// DISTINCT-FROM: kb/download-retry.mjs — that retries the customer updater's HTTPS stream by error code; this
+// classifies and retries the pipeline's `gh`/`git` subprocess reads by what they printed.
+//
+// scripts/transient-gh.mjs — ONE rule for what a transient GitHub/API/git failure looks like, and ONE bounded
+// retry for it, shared by every read in the corpus nightly (ADR-0091, fault classes in CONTRIBUTING.md).
+//
+// THE FAILURE THIS EXISTS TO END (measured on 38 corpus nights, 2026-09-21 .. 2026-10-18). Twenty-four nights
+// failed; the causes were a gist API rate limit, a publisher that could not re-read the release it had just
+// created, a canary refused one anonymous read, a git credential prompt on a clone -- each a single blip at a
+// single `gh`/`git`/`fetch` call, each unretried, each the whole night for every customer. Before this module
+// every call site either had no retry or its own private idea of "transient" (the canary's status set, the
+// gist transport's regexes, the reconciler's exit-status classes). The rule is now written once:
+//
+//   TRANSIENT  a rate limit (primary or secondary), HTTP 429/408/5xx, a connection reset/refused/timed out, a
+//              DNS hiccup, a TLS handshake failure, a hung-up socket, git's credential prompt on an anonymous
+//              fetch ("could not read Username"), a partial transfer ("early EOF", "RPC failed").
+//   NOT        HTTP 404/410 (gone: the ifGone carry in source-coverage.mjs owns it), a bare HTTP 403 from an
+//              authenticated gh (a permission answer, e.g. "Resource not accessible by integration"), "release
+//              not found" (the publisher's absence proof), a signature, digest or schema refusal, a missing
+//              binary (ENOENT). Those are answers, not weather; retrying them only delays the honest failure.
+//
+// Anonymous `fetch` reads from a shared runner address are the one place a bare 403 IS transient (GitHub's
+// per-IP throttle answers 403): that status set, TRANSIENT_HTTP, lives here too so the canary and any other
+// anonymous reader share it rather than restating it.
+//
+// WRITES ARE NEVER RETRIED BLINDLY. `gh release create` uploads assets; a retry after a half-finished create
+// collides with the release it left behind. `retryingGh` retries reads and idempotent edits only; a create or
+// any `gh api` POST/PUT/PATCH/DELETE runs exactly once and reports what happened.
+
+/** Anonymous-fetch statuses a shared runner address sees for a moment (GitHub throttles anonymous reads with 403). */
+export const TRANSIENT_HTTP = new Set([403, 408, 429, 500, 502, 503, 504]);
+
+export const DEFAULT_ATTEMPTS = 3;
+export const DEFAULT_BASE_DELAY_MS = 15_000;
+/** The wait before retry `n` is `base * n`. RUVNET_TRANSIENT_RETRY_DELAY_MS is the test seam (the suite sets 0 so a
+ * fake gh that answers "gateway timeout" fails in milliseconds, not after the 45 s a real night would wait). */
+export function defaultBaseDelayMs(fallback = DEFAULT_BASE_DELAY_MS) {
+  const seam = Number(process.env.RUVNET_TRANSIENT_RETRY_DELAY_MS);
+  return Number.isFinite(seam) && seam >= 0 && process.env.RUVNET_TRANSIENT_RETRY_DELAY_MS !== undefined ? seam : fallback;
+}
+
+const TRANSIENT_TEXT = /\brate limit|secondary rate|abuse detection|HTTP (408|429|5\d\d)\b|\b(500|502|503|504) (Internal Server Error|Bad Gateway|Service Unavailable|Gateway Time-?out)|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|EPIPE|connection reset|connection refused|timed out|timeout|TLS handshake|socket hang up|could not resolve host|no such host|dial tcp|i\/o timeout|unexpected EOF|early EOF|RPC failed|remote end hung up|could not read Username|unable to access|temporarily unavailable|temporary failure/i;
+
+/** What a failed subprocess said -- stderr, then stdout, then the spawn error -- as one string for classification. */
+export function failureText(result) {
+  return [result?.stderr, result?.stdout, result?.error?.message].map((part) => String(part ?? '')).join('\n');
+}
+
+/** The one classifier: true when the text describes weather, not an answer. A missing binary is never weather. */
+export function isTransientText(text) {
+  const message = String(text ?? '');
+  if (/\bENOENT\b/.test(message)) return false;
+  return TRANSIENT_TEXT.test(message);
+}
+
+/** A spawnSync-shaped result that failed transiently. */
+export function isTransientResult(result) {
+  if (!result) return false;
+  if (!result.error && result.status === 0) return false;
+  if (result.error?.code === 'ENOENT') return false;
+  return isTransientText(failureText(result));
+}
+
+/** Blocks the thread for `ms`; the pipeline's gh/git callers are synchronous spawnSync loops. Injectable in tests. */
+export function sleepSync(ms) {
+  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const delayFor = (attempt, baseDelayMs) => baseDelayMs * attempt;
+
+/**
+ * Run `fn` (which THROWS on failure) up to `attempts` times while the failure is transient, waiting
+ * baseDelayMs * attempt between tries. The last error is rethrown unchanged, so callers keep their own messages.
+ */
+export function retryTransient(fn, { attempts = DEFAULT_ATTEMPTS, baseDelayMs = defaultBaseDelayMs(), sleep = sleepSync,
+  isTransient = (error) => isTransientText(error?.message), onRetry = () => {} } = {}) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return fn(attempt);
+    } catch (error) {
+      if (attempt >= attempts || !isTransient(error)) throw error;
+      onRetry({ attempt, error, delayMs: delayFor(attempt, baseDelayMs) });
+      sleep(delayFor(attempt, baseDelayMs));
+    }
+  }
+}
+
+/** The async twin of retryTransient, for callers whose work (or sleep) is a promise. */
+export async function retryTransientAsync(fn, { attempts = DEFAULT_ATTEMPTS, baseDelayMs = defaultBaseDelayMs(),
+  sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+  isTransient = (error) => isTransientText(error?.message), onRetry = () => {} } = {}) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      if (attempt >= attempts || !isTransient(error)) throw error;
+      onRetry({ attempt, error, delayMs: delayFor(attempt, baseDelayMs) });
+      await sleep(delayFor(attempt, baseDelayMs));
+    }
+  }
+}
+
+/**
+ * Run `fn` (which RETURNS a spawnSync-shaped result, never throws) up to `attempts` times while the result is a
+ * transient failure. Returns the last result, so callers that read `status`/`stderr` keep doing exactly that.
+ */
+export function retryTransientResult(fn, { attempts = DEFAULT_ATTEMPTS, baseDelayMs = defaultBaseDelayMs(),
+  sleep = sleepSync, onRetry = () => {} } = {}) {
+  let result;
+  for (let attempt = 1; ; attempt += 1) {
+    result = fn(attempt) || {};
+    if (attempt >= attempts || !isTransientResult(result)) return result;
+    onRetry({ attempt, result, delayMs: delayFor(attempt, baseDelayMs) });
+    sleep(delayFor(attempt, baseDelayMs));
+  }
+}
+
+const GH_WRITE_VERBS = new Set(['create', 'delete', 'upload', 'delete-asset']);
+const REST_WRITE_FLAGS = new Set(['-f', '-F', '--input', '--field', '--raw-field']);
+const METHOD_FLAGS = new Set(['-X', '--method']);
+
+/**
+ * Is this `gh` argument vector a write that must run exactly once? `release edit` is an idempotent PATCH and is
+ * NOT a write here: re-sending the same flags after a timeout converges on the same state. `gh api` is a write
+ * when it names a non-GET method or carries a field flag (gh then sends POST); `gh api graphql` always POSTs.
+ */
+export function isGhWrite(args) {
+  const argv = (args || []).map(String);
+  if (argv[0] === 'api') {
+    const methodAt = argv.findIndex((token) => METHOD_FLAGS.has(token));
+    if (methodAt >= 0 && String(argv[methodAt + 1] || '').toUpperCase() !== 'GET') return true;
+    if (argv[1] === 'graphql') return true;
+    return argv.some((token) => REST_WRITE_FLAGS.has(token));
+  }
+  return argv[0] === 'release' && GH_WRITE_VERBS.has(argv[1]);
+}
+
+/**
+ * A `gh` runner over a spawnSync-shaped `run` that retries transient failures of READS and idempotent edits,
+ * bounded, and runs a write exactly once. `prefix` is the RUVNET_GH_SCRIPT test seam (scripts/release.mjs).
+ */
+export function retryingGh({ run, command = 'gh', prefix = [], options = {}, sleep = sleepSync, attempts = DEFAULT_ATTEMPTS,
+  baseDelayMs = defaultBaseDelayMs(), onRetry = () => {} } = {}) {
+  if (typeof run !== 'function') throw new Error('retryingGh needs a spawnSync-shaped run function');
+  return (args) => {
+    const once = () => run(command, [...prefix, ...args], options) || {};
+    if (isGhWrite(args)) return once();
+    return retryTransientResult(once, { attempts, baseDelayMs, sleep, onRetry: (event) => onRetry({ ...event, args }) });
+  };
+}