ruvnet-brain 4.3.26 → 4.3.28

package/scripts/gist-receipts.mjs

@@ -33,6 +33,7 @@ import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest, validateGistAggregateReceipt } from './coverage-integrity.mjs';
 import { promoteArtifactSet } from '../kb/incremental-refresh.mjs';
 import { writeRvfGeneration } from './rvf-generation.mjs';
+import { fetchGistGitSnapshot } from './gist-git-transport.mjs';
 
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.rst']);
@@ -45,6 +46,7 @@ const HEX_GIST = /^[a-f0-9]{20,64}$/;
 const OWNER_RE = /^[A-Za-z0-9-]{1,39}$/;
 const compareCanonicalText = (left, right) => String(left) < String(right) ? -1
   : String(left) > String(right) ? 1 : 0;
+const VERIFIED_CAPTURE_SETS = new WeakMap();
 
 function validDate(value) {
   return typeof value === 'string' && Number.isFinite(Date.parse(value));
@@ -122,38 +124,67 @@ const RATE_LIMIT_RE = /rate limit/i;
 const NOT_FOUND_RE = /\bnot found\b|HTTP 404/i;
 const FORBIDDEN_INTEGRATION_RE = /resource not accessible by integration/i;
 const TRANSIENT_RE = /timeout|timed out|TLS handshake|ECONNRESET|ECONNREFUSED|EAI_AGAIN|temporary failure|HTTP 5\d\d|HTTP 429|socket hang up/i;
+const MAX_RATE_LIMIT_WAIT_MS = 15 * 60 * 1000;
+
+function retryDelay(error, attempt, retryDelayMs) {
+  if (error?.code !== 'GIST_RATE_LIMITED') return retryDelayMs * attempt;
+  const retryAfter = Number(error.headers?.['retry-after']);
+  const resetAt = Number(error.headers?.['x-ratelimit-reset']);
+  const requested = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000
+    : Number.isFinite(resetAt) && resetAt > 0 ? Math.max(0, resetAt * 1000 - Date.now()) : retryDelayMs * attempt;
+  return requested > MAX_RATE_LIMIT_WAIT_MS ? null : Math.max(retryDelayMs * attempt, requested);
+}
 
 export class GistFetchError extends Error {
-  constructor(message, { code, gistId, status, retryable = false } = {}) {
+  constructor(message, { code, gistId, status, headers = {}, retryable = false } = {}) {
     super(message);
     this.name = 'GistFetchError';
     this.code = code;
     this.gistId = gistId;
     if (status !== undefined) this.status = status;
+    if (headers && Object.keys(headers).length) this.headers = headers;
     this.retryable = retryable;
   }
 }
 
-function classifyGistFetchFailure(stderr, gistId) {
+function classifyGistFetchFailure(stderr, gistId, { status, headers = {} } = {}) {
   const message = String(stderr || '').trim();
-  if (NOT_FOUND_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} was moved or deleted: ${message}`,
-      { code: 'GIST_NOT_FOUND', gistId, retryable: false });
+  const responseStatus = status ?? (Number(message.match(/\bHTTP\s+(\d{3})\b/i)?.[1]) || undefined);
+  const safeHeaders = Object.fromEntries(['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']
+    .flatMap((key) => headers[key] == null ? [] : [[key, String(headers[key])]]));
+  const responseDetail = [responseStatus ? `HTTP ${responseStatus}` : '', Object.keys(safeHeaders).length
+    ? `headers=${JSON.stringify(safeHeaders)}` : '', message].filter(Boolean).join('; ');
+  if (responseStatus === 404 || (!responseStatus && NOT_FOUND_RE.test(message))) {
+    return new GistFetchError(`gist ${gistId} was moved or deleted: ${responseDetail}`,
+      { code: 'GIST_NOT_FOUND', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
   }
-  if (FORBIDDEN_INTEGRATION_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch rejected -- token lacks gist scope: ${message}`,
-      { code: 'GIST_FORBIDDEN', gistId, retryable: false });
+  if (RATE_LIMIT_RE.test(message) || (responseStatus === 403 && headers['x-ratelimit-remaining'] === '0')
+    || (responseStatus === 429 && Boolean(headers['retry-after']))) {
+    return new GistFetchError(`gist ${gistId} fetch rate-limited: ${responseDetail}`,
+      { code: 'GIST_RATE_LIMITED', gistId, status: responseStatus, headers: safeHeaders, retryable: true });
   }
-  if (RATE_LIMIT_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch rate-limited: ${message}`,
-      { code: 'GIST_RATE_LIMITED', gistId, retryable: true });
+  if (responseStatus === 403 && (FORBIDDEN_INTEGRATION_RE.test(message) || !headers['x-ratelimit-remaining'])) {
+    return new GistFetchError(`gist ${gistId} fetch rejected (HTTP 403): ${responseDetail}`,
+      { code: 'GIST_FORBIDDEN', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
   }
-  if (TRANSIENT_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch failed transiently: ${message}`,
-      { code: 'GIST_TRANSIENT_FAILURE', gistId, retryable: true });
+  if (TRANSIENT_RE.test(message) || (responseStatus >= 500 && responseStatus < 600) || responseStatus === 429) {
+    return new GistFetchError(`gist ${gistId} fetch failed transiently: ${responseDetail}`,
+      { code: 'GIST_TRANSIENT_FAILURE', gistId, status: responseStatus, headers: safeHeaders, retryable: true });
   }
-  return new GistFetchError(`gist ${gistId} fetch failed: ${message}`,
-    { code: 'GIST_FETCH_FAILED', gistId, retryable: false });
+  return new GistFetchError(`gist ${gistId} fetch failed: ${responseDetail}`,
+    { code: 'GIST_FETCH_FAILED', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
+}
+
+function parseGhResponse(output) {
+  const text = String(output || '');
+  const match = text.match(/^HTTP\/\S+\s+(\d+)\r?\n([\s\S]*?)\r?\n\r?\n([\s\S]*)$/m);
+  if (!match) return { status: undefined, headers: {}, body: text };
+  const headers = {};
+  for (const line of match[2].split(/\r?\n/)) {
+    const split = line.indexOf(':');
+    if (split > 0) headers[line.slice(0, split).trim().toLowerCase()] = line.slice(split + 1).trim();
+  }
+  return { status: Number(match[1]), headers, body: match[3] };
 }
 
 function defaultSleep(ms) {
@@ -172,11 +203,14 @@ export async function defaultFetchGist(id, { spawn = spawnSync, retries = 3, ret
   const attempts = Math.max(1, retries);
   let lastError;
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    const result = spawn('gh', ['api', `gists/${id}`], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-    if (result.status === 0) return JSON.parse(result.stdout);
-    lastError = classifyGistFetchFailure(result.stderr, id);
+    const result = spawn('gh', ['api', '--include', `gists/${id}`], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const response = parseGhResponse(result.stdout);
+    if (result.status === 0) return JSON.parse(response.body);
+    lastError = classifyGistFetchFailure(`${result.stderr || ''}\n${response.body || ''}`, id, response);
     if (!lastError.retryable || attempt === attempts) throw lastError;
-    await sleep(retryDelayMs * attempt);
+    const delay = retryDelay(lastError, attempt, retryDelayMs);
+    if (delay === null) throw lastError;
+    await sleep(delay);
     if (signal?.aborted) throw abortError(signal);
   }
   throw lastError;
@@ -185,17 +219,34 @@ export async function defaultFetchGist(id, { spawn = spawnSync, retries = 3, ret
 // The unauthenticated fallback used ONLY for the specific 403 "no gist scope" rejection. Mirrors
 // source-coverage.mjs's listGistsUnauthenticated: same env var, same accept header, same
 // unauthenticated-quota reasoning. `fetchImpl` is a test seam (default: global fetch).
-async function fetchPublicGistDetail(id, { fetchImpl = globalThis.fetch, signal } = {}) {
+async function fetchPublicGistDetail(id, { fetchImpl = globalThis.fetch, retries = 3, retryDelayMs = 300,
+  sleep = defaultSleep, signal } = {}) {
   const apiBase = process.env.RUVNET_GISTS_API || 'https://api.github.com';
-  const response = await fetchImpl(`${apiBase}/gists/${id}`, {
-    headers: { accept: 'application/vnd.github+json', 'user-agent': 'ruvnet-brain-gist-receipts' },
-    signal,
-  });
-  if (!response.ok) {
-    throw new GistFetchError(`gist ${id} public detail fetch failed: HTTP ${response.status}`,
-      { code: 'GIST_FETCH_FAILED', gistId: id, status: response.status, retryable: false });
+  const attempts = Math.max(1, retries);
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const response = await fetchImpl(`${apiBase}/gists/${id}`, {
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'ruvnet-brain-gist-receipts' },
+      signal,
+    });
+    if (response.ok) return response.json();
+    const headers = {};
+    for (const key of ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']) {
+      const value = response.headers?.get?.(key);
+      if (value != null) headers[key] = value;
+    }
+    const body = await response.json?.().catch?.(() => null);
+    const classified = classifyGistFetchFailure(`public detail fetch failed: HTTP ${response.status} ${body?.message || ''}`, id,
+      { status: response.status, headers });
+    const error = new GistFetchError(`gist ${id} public detail fetch failed: ${classified.message}`,
+      { code: classified.code, gistId: id, status: response.status, headers: classified.headers,
+        retryable: classified.retryable });
+    if (!error.retryable || attempt === attempts) throw error;
+    const delay = retryDelay(error, attempt, retryDelayMs);
+    if (delay === null) throw error;
+    await sleep(delay);
+    if (signal?.aborted) throw abortError(signal);
   }
-  return response.json();
+  throw new Error(`gist ${id} public detail retries exhausted`);
 }
 
 // The transport `captureGistSources` uses by default for per-gist DETAIL. Wraps `defaultFetchGist`
@@ -229,9 +280,18 @@ export async function defaultFetchRaw(file, { fetchImpl = globalThis.fetch, retr
         headers: { 'user-agent': 'ruvnet-brain-gist-receipts' }, signal,
       });
       if (response.ok) return Buffer.from(await response.arrayBuffer());
-      const transient = response.status === 429 || (response.status >= 500 && response.status < 600);
-      lastError = new GistFetchError(`raw gist fetch failed: HTTP ${response.status}`,
-        { code: transient ? 'GIST_RAW_TRANSIENT_FAILURE' : 'GIST_RAW_FETCH_FAILED', status: response.status, retryable: transient });
+      const headers = {};
+      for (const key of ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']) {
+        const value = response.headers?.get?.(key);
+        if (value != null) headers[key] = value;
+      }
+      const rateLimited = response.status === 403 && (headers['x-ratelimit-remaining'] === '0'
+        || RATE_LIMIT_RE.test(response.statusText || '')) || response.status === 429;
+      const transient = rateLimited || (response.status >= 500 && response.status < 600);
+      lastError = new GistFetchError(`raw gist fetch failed: HTTP ${response.status}; headers=${JSON.stringify(
+        Object.fromEntries(Object.entries(headers).filter(([key]) => ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id'].includes(key))))}`,
+      { code: rateLimited ? 'GIST_RATE_LIMITED' : transient ? 'GIST_RAW_TRANSIENT_FAILURE' : 'GIST_RAW_FETCH_FAILED',
+        status: response.status, headers, retryable: transient });
       if (!transient) throw lastError;
     } catch (error) {
       if (error instanceof GistFetchError) { lastError = error; if (!error.retryable) throw error; }
@@ -243,7 +303,9 @@ export async function defaultFetchRaw(file, { fetchImpl = globalThis.fetch, retr
       }
     }
     if (attempt === attempts) throw lastError;
-    await sleep(retryDelayMs * attempt);
+    const delay = retryDelay(lastError, attempt, retryDelayMs);
+    if (delay === null) throw lastError;
+    await sleep(delay);
     if (signal?.aborted) throw abortError(signal);
   }
   throw lastError;
@@ -340,18 +402,49 @@ function reusableCachedGist(cached, stub) {
   return 'reuse';
 }
 
-export async function captureGistSources({ observation, cache = null, fetchDetail = defaultFetchDetail,
-  fetchRaw = defaultFetchRaw, signal, now = () => new Date().toISOString() } = {}) {
+export async function captureGistSources({ observation, cache = null, fetchDetail = null,
+  fetchRaw = defaultFetchRaw, fetchGitSnapshot = fetchGistGitSnapshot, signal,
+  now = () => new Date().toISOString() } = {}) {
   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) {
     throw new Error('source observation has missing or duplicate gist ids');
   }
+  const observedRowsSha256 = digest({ owner: observation.owner, observedAt: observation.observedAt, rows: stubs });
   const gists = {};
   const reused = [];
   const fetched = [];
   for (const stub of [...stubs].sort((a, b) => String(a.id).localeCompare(String(b.id)))) {
     if (signal?.aborted) throw abortError(signal);
+    if (!fetchDetail) {
+      // 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 files = [];
+      for (const source of snapshot.files) {
+        const filename = source.filename;
+        if (!TEXT_EXT.has(path.extname(filename).toLowerCase())) {
+          files.push({ filename, included: false, reason: 'non-text policy exclusion', size: source.size,
+            sourceGit: { ...source.sourceGit, captureMethod: 'public-bare-git-v1', revisionKind: 'git-commit',
+              observedAt: observation.observedAt, observedRowsSha256,
+              sourceObservationSha256: observation.observationSha256 } });
+          continue;
+        }
+        let text;
+        try { text = new TextDecoder('utf-8', { fatal: true }).decode(source.body); }
+        catch { throw new Error(`gist ${stub.id}/${filename} is not valid UTF-8 text`); }
+        files.push({ filename, included: true, sha256: sha256(source.body), bytes: source.size,
+          body: text, sourceGit: { ...source.sourceGit, captureMethod: 'public-bare-git-v1', revisionKind: 'git-commit',
+            observedAt: observation.observedAt, observedRowsSha256,
+            sourceObservationSha256: observation.observationSha256 } });
+      }
+      if (files.length !== snapshot.treeFileCount) throw new Error(`gist ${stub.id} Git inventory changed during capture`);
+      gists[stub.id] = { gistId: stub.id, versionSha: snapshot.headSha, updatedAt: stub.updated_at,
+        ingestedAt: now(), complete: true, files };
+      fetched.push(stub.id);
+      continue;
+    }
     const cached = cache?.gists?.[stub.id];
     const verdict = cached ? reusableCachedGist(cached, stub) : 'miss';
     if (verdict === 'tampered') {
@@ -386,14 +479,31 @@ export async function captureGistSources({ observation, cache = null, fetchDetai
       complete: files.length === Object.keys(full.files || {}).length, files };
     fetched.push(stub.id);
   }
-  return {
+  const captured = {
     owner: observation.owner,
+    observedRowsSha256,
     observedAt: observation.observedAt,
     sourceObservationSha256: observation.observationSha256,
     generatedAt: now(),
     gists,
     reuseEvidence: { reused, fetched },
   };
+  VERIFIED_CAPTURE_SETS.set(captured, {
+    fingerprint: digest(captured),
+    owner: observation.owner,
+    observedRowsSha256,
+    sourceObservationSha256: observation.observationSha256,
+  });
+  return captured;
+}
+
+function isCurrentVerifiedCapture(captured, observation) {
+  const proof = captured && typeof captured === 'object' ? VERIFIED_CAPTURE_SETS.get(captured) : null;
+  return Boolean(proof && proof.owner === observation?.owner
+    && proof.observedRowsSha256 === digest({ owner: observation?.owner,
+      observedAt: observation?.observedAt, rows: observation?.gists?.rows })
+    && proof.sourceObservationSha256 === observation?.observationSha256
+    && proof.fingerprint === digest(captured));
 }
 
 // ── stage 2: render ──────────────────────────────────────────────────────────────────────────────
@@ -462,6 +572,25 @@ export function validateGistReceipt({ receipt, observation = null, passagesFile,
     if (!validDate(row?.updatedAt) || !validDate(row?.ingestedAt)) {
       throw new Error(`gist ${gistId} has an invalid updatedAt/ingestedAt timestamp`);
     }
+    const sourceProofs = (row?.files || []).map((file) => file?.sourceGit).filter(Boolean);
+    if (sourceProofs.length && sourceProofs.length !== row.files.length) {
+      throw new Error(`gist ${gistId} mixes Git-bound and unbound file evidence`);
+    }
+    if (sourceProofs.length && sourceProofs.some((proof) => !HEX40.test(String(proof.headSha || ''))
+      || !HEX40.test(String(proof.treeSha || '')) || !HEX40.test(String(proof.blobSha || ''))
+      || proof.captureMethod !== 'public-bare-git-v1' || proof.revisionKind !== 'git-commit'
+      || !validDate(proof.observedAt) || proof.sourceObservationSha256 !== receipt.sourceObservationSha256
+      || !HEX64.test(String(proof.observedRowsSha256 || ''))
+      || !Number.isSafeInteger(proof.treeFileCount) || proof.treeFileCount !== row.files.length
+      || proof.observedTruncated !== false || proof.observedFileCount !== proof.treeFileCount
+      || proof.headSha !== row.versionSha || proof.observed !== true
+      || !HEX40.test(String(proof.observedRawRevisionSha || ''))
+      || !['blob', 'commit'].includes(proof.observedRawRevisionKind)
+      || proof.observedRawBlobSha !== proof.blobSha
+      || sourceProofs.some((other) => other.treeSha !== proof.treeSha || other.headSha !== proof.headSha
+        || other.observedRowsSha256 !== proof.observedRowsSha256))) {
+      throw new Error(`gist ${gistId} has an incomplete Git snapshot proof`);
+    }
     for (const file of row?.files || []) {
       if (!validateFilename(file?.filename)) throw new Error(`gist ${gistId} has an unsafe or missing filename`);
     }
@@ -517,8 +646,9 @@ export async function buildGistAggregate({ observation, cache = null, outDir, ro
       sourceMetadata: null, files: [], sourceReceipt: null, reuseEvidence: { reused: [], fetched: [] } };
   }
 
-  const captured = await captureGistSources({
-    observation, cache, fetchDetail: transport.fetchDetail, fetchRaw: transport.fetchRaw, signal, now,
+  const captured = isCurrentVerifiedCapture(cache, observation) ? cache : await captureGistSources({
+    observation, cache, fetchDetail: transport.fetchDetail, fetchRaw: transport.fetchRaw,
+    fetchGitSnapshot: transport.fetchGitSnapshot, signal, now,
   });
   const { passageBytes, metadata, gistRecords } = renderGistPassages({ captured, generatedAt: captured.generatedAt });
   const includedFileCount = Object.values(captured.gists)

package/scripts/host-install-matrix.mjs

@@ -32,6 +32,11 @@ import { runRetrievalCanaries, validateRetrievalCanaryReceipt, resolveInstalledC
 
 /** The three host shapes a release must survive. ONE name each, for every consumer. */
 export const HOST_MODES = Object.freeze(['claude', 'codex', 'dual']);
+export const SELF_STORE_PROOF_QUERY = 'repo:ruvnet-brain What is the RuvNet Brain release evidence workflow?';
+export const SELF_STORE_PROOF_K = 1;
+export const RELEASE_SEARCH_QUERY = 'repo:ruvnet-brain How does RuvNet Brain prove a public release artifact?';
+export const HOST_WARMUP_TIMEOUT_MS = 300_000;
+export const RELEASE_SEARCH_DEADLINE_MS = 30_000;
 
 /** Which CLIs each mode is allowed to see. A codex-only box genuinely has no `claude`. */
 export const MODE_HOSTS = Object.freeze({
@@ -204,6 +209,7 @@ export async function runHostMatrixAsync({
   verifyGrounding = verifyInstalledGrounding,
   resolveMcpServer = resolveInstalledMcpServer,
   retrieval,
+  sequentialSearches = false,
 }) {
   const spec = VARIANTS[variant];
   if (!spec) throw new Error(`unknown host-matrix variant: ${variant}`);
@@ -251,32 +257,57 @@ export async function runHostMatrixAsync({
 
   const prewarmContext = contexts[0];
   const prewarmReader = path.join(prewarmContext.env.RUVNET_BRAIN_KB, 'forge-ask-all.mjs');
+  // This query only primes the shared model cache. Keep it in the Brain's own bounded store so
+  // Mac/Windows/Linux runner speed does not determine whether the later real host searches run.
+  // The following MCP matrix remains the measured, source-grounded candidate acceptance.
   const prewarm = await runCommand(process.execPath, [prewarmReader, '--dir', prewarmContext.env.RUVNET_BRAIN_KB,
-    '--q', 'How does RuvNet Brain prove a public release artifact?', '--k', '1'], {
+    '--q', RELEASE_SEARCH_QUERY, '--k', '1', '--pool', '8',
+    '--repos', 'ruvnet-brain', '--bounded'], {
     cwd: prewarmContext.env.RUVNET_BRAIN_KB, env: prewarmContext.env, timeout: 300_000,
   });
   if (prewarm.error || prewarm.status !== 0) {
-    return { verdict: 'FAIL', fixtures: {}, error: `shared model prewarm failed (${processDiagnostic(prewarm)})` };
+    const detail = String(prewarm.stderr || prewarm.stdout || '').trim().split('\n').slice(-8).join(' | ').slice(-1600);
+    return { verdict: 'FAIL', fixtures: {}, error: `shared model prewarm failed (${processDiagnostic(prewarm)})${detail ? `; ${detail}` : ''}` };
   }
   const prewarmGrounding = await verifyGrounding(String(prewarm.stdout || ''), prewarmContext.env.RUVNET_BRAIN_KB);
   if (!prewarmGrounding?.grounded) {
     return { verdict: 'FAIL', fixtures: {}, error: 'shared model prewarm returned no grounded source receipt' };
   }
 
-  const searches = await Promise.all(contexts.map(async (context) => {
+  const searchOne = async (context) => {
     let session;
     try {
       const serverPath = resolveMcpServer(context);
       // One installed worker per host: model/store state survives smoke and every sealed case.
       session = runMcpSearch === runInstalledMcpSearch ? createInstalledMcpSession({ serverPath, env: context.env }) : null;
       const searchMcp = session ? (args) => session.search(args) : runMcpSearch;
-      const processResult = await searchMcp({ mode: context.mode, serverPath, env: context.env });
+      // The installed shell warms its in-process models and stores asynchronously from MCP
+      // initialize. Candidate qualification must give that same worker the same cited readiness
+      // probe used by the public verifier before timing the first user search; a separate CLI
+      // prewarm only primes disk cache and cannot warm this worker's process memory.
+      const warmupResult = await searchMcp({ mode: context.mode, serverPath, env: context.env,
+        query: SELF_STORE_PROOF_QUERY, k: SELF_STORE_PROOF_K, timeoutMs: HOST_WARMUP_TIMEOUT_MS });
+      const warmupOutput = `${warmupResult.stdout || ''}${warmupResult.stderr || ''}`;
+      if (warmupResult.error || warmupResult.status !== 0) {
+        return { context, processResult: warmupResult,
+          error: `MCP warmup failed for ${context.mode} (${processDiagnostic(warmupResult)}): ${warmupOutput.slice(-2000)}` };
+      }
+      const warmupGrounding = await verifyGrounding(warmupOutput, context.env.RUVNET_BRAIN_KB);
+      if (!warmupGrounding?.grounded || warmupGrounding.receipt?.repo !== 'ruvnet-brain') {
+        return { context, processResult: warmupResult, warmupMs: warmupResult.broadMs,
+          error: `MCP self-store warmup grounding unproven for ${context.mode}` };
+      }
+      const processResult = await searchMcp({ mode: context.mode, serverPath, env: context.env,
+        query: RELEASE_SEARCH_QUERY, k: 5,
+        timeoutMs: RELEASE_SEARCH_DEADLINE_MS });
       const output = `${processResult.stdout || ''}${processResult.stderr || ''}`;
       if (processResult.error || processResult.status !== 0) {
-        return { context, processResult, error: `MCP search failed for ${context.mode} (${processDiagnostic(processResult)}): ${output.slice(-2000)}` };
+        return { context, processResult, warmupMs: warmupResult.broadMs, warmupGrounding,
+          error: `MCP search failed for ${context.mode} (${processDiagnostic(processResult)}): ${output.slice(-2000)}` };
       }
       const grounding = await verifyGrounding(output, context.env.RUVNET_BRAIN_KB);
-      if (!grounding?.grounded) return { context, processResult, error: `MCP search grounding unproven for ${context.mode}` };
+      if (!grounding?.grounded) return { context, processResult, warmupMs: warmupResult.broadMs,
+        warmupGrounding, error: `MCP search grounding unproven for ${context.mode}` };
       let receipt;
       if (retrieval) {
         receipt = await runRetrievalCanaries({ ...retrieval,
@@ -288,17 +319,29 @@ export async function runHostMatrixAsync({
           citationResolver: (matched, expected) => resolveInstalledCanaryCitation({ kbDir: context.env.RUVNET_BRAIN_KB, matched, expected }),
         });
         try { validateRetrievalCanaryReceipt(receipt, { plan: retrieval.plan }); }
-        catch (error) { return { context, processResult, grounding, retrieval: receipt, error: `${context.mode} canary rejected: ${error.message}` }; }
+        catch (error) { return { context, processResult, warmupMs: warmupResult.broadMs,
+          warmupGrounding, grounding, retrieval: receipt, error: `${context.mode} canary rejected: ${error.message}` }; }
       }
-      return { context, processResult, grounding, ...(receipt ? { retrieval: receipt } : {}) };
+      return { context, processResult, warmupMs: warmupResult.broadMs, warmupGrounding,
+        grounding, ...(receipt ? { retrieval: receipt } : {}) };
     } catch (error) {
       return { context, processResult: { status: null, error }, error: `${context.mode} host search failed: ${error.message}` };
     } finally { await session?.close(); }
-  }));
-  const fixtures = Object.fromEntries(searches.map(({ context, processResult, grounding, retrieval, error }) => [context.mode, {
+  };
+  const searches = [];
+  if (sequentialSearches) {
+    for (const context of contexts) searches.push(await searchOne(context));
+  } else {
+    searches.push(...await Promise.all(contexts.map(searchOne)));
+  }
+  const fixtures = Object.fromEntries(searches.map(({ context, processResult, warmupMs, warmupGrounding,
+    grounding, retrieval, error }) => [context.mode, {
     status: error ? 'FAIL' : 'PASS',
     version,
     process: processIdentity(processResult),
+    warmupMs: Number.isFinite(warmupMs) ? warmupMs : null,
+    ...(warmupGrounding?.receipt ? { warmupGrounding: warmupGrounding.receipt } : {}),
+    searchMs: Number.isFinite(processResult.broadMs) ? processResult.broadMs : null,
     ...(grounding?.receipt ? { grounding: grounding.receipt } : {}),
     ...(retrieval ? { retrieval } : {}),
     ...(error ? { error } : {}),
@@ -395,7 +438,7 @@ export function createInstalledMcpSession({ serverPath, env, timeout = 300_000,
     pending.set(id, { resolve, reject });
     child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
   });
-  const execute = async ({ query = 'How does RuvNet Brain prove a public release artifact?', k = 5,
+  const execute = async ({ query = RELEASE_SEARCH_QUERY, k = 5,
     timeoutMs = timeout } = {}) => {
     if (terminalError) return { status: null, error: terminalError, signal: exitSignal, stdout: '', stderr };
     stderr = '';

package/scripts/ingest-gists.mjs

@@ -194,10 +194,13 @@ async function main() {
   }
 
   const observedAt = new Date().toISOString();
-  const rows = gists.map((g) => ({ id: g.id, updated_at: g.updated_at, files: g.files }));
+  const rows = gists.map((g) => ({ id: g.id, updated_at: g.updated_at, html_url: g.html_url,
+    truncated: g.truncated, files: g.files }));
   const observation = {
     owner: OWNER, observedAt,
-    observationSha256: digest({ owner: OWNER, rows: rows.map(({ id, updated_at }) => ({ id, updated_at })) }),
+    // Bind the exact listed file inventory and its truncation indicator. A timestamp-only digest
+    // could otherwise reuse a capture after the API changes a file's pinned raw blob or completeness.
+    observationSha256: digest({ owner: OWNER, rows }),
     gists: { rows },
   };
   const now = () => observedAt;

package/scripts/installed-brain-health.mjs

@@ -0,0 +1,99 @@
+// ADR-089: describe installed identities without confusing a validator pin with search-engine proof.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readInstalledRuntime, isCorpusReleaseTag } from '../kb/corpus-release-identity.mjs';
+import { cmpVersion } from './stack-sync.mjs';
+import { isRuntimeFile } from './approved-runtime.mjs';
+
+const SEARCH_FILES = ['forge-mcp-all.mjs', 'forge-ask-all.mjs', 'forge-rerank.mjs', 'card-lane.mjs'];
+// Keep the doctor probe answerable and bounded. A health probe must exercise a real indexed
+// source/citation path; it must not turn an unclear broad question into an all-corpus rerank.
+export const DOCTOR_SMOKE_QUERY = 'What package name is declared in the RuvNet Brain KB package manifest?';
+export function doctorSmokeArgs(cacheDir) {
+  return ['forge-ask-all.mjs', '--dir', cacheDir, '--q', DOCTOR_SMOKE_QUERY,
+    '--repos', 'ruvnet-brain', '--k', '3', '--pool', '8', '--bounded'];
+}
+const version = value => typeof value === 'string' && /^v?\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(value)
+  ? value.replace(/^v/, '') : null;
+
+export function inspectInstalledBrain(kbDir, packageVersion) {
+  const result = { healthy: false, packageVersion, searchVersion: null, corpusTag: null,
+    validatorVersion: null, searchFiles: {}, issues: [] };
+  let source;
+  try { source = JSON.parse(fs.readFileSync(path.join(kbDir, 'SOURCE.json'), 'utf8')); }
+  catch { result.issues.push('SOURCE.json is missing or unreadable'); }
+  result.searchVersion = version(source?.brainVersion) || version(source?.releaseTag);
+  result.corpusTag = isCorpusReleaseTag(source?.corpusReleaseTag) ? source.corpusReleaseTag : null;
+  if (!result.searchVersion) result.issues.push('the search engine version is unverified');
+  if (version(source?.brainVersion) && version(source?.releaseTag)
+    && version(source.brainVersion) !== version(source.releaseTag)) {
+    result.issues.push('SOURCE.json runtime version and release tag disagree');
+  }
+  const pin = readInstalledRuntime(kbDir);
+  result.validatorVersion = pin.brainVersion;
+  if (!pin.ok) result.issues.push(pin.reason);
+  if (pin.ok && result.searchVersion && version(pin.brainVersion) !== result.searchVersion) {
+    result.issues.push(`validator runtime ${pin.brainVersion} and search engine ${result.searchVersion} differ`);
+  }
+  const expected = version(packageVersion);
+  if (expected && result.searchVersion && cmpVersion(result.searchVersion, expected) < 0) {
+    result.issues.push(`search engine ${result.searchVersion} is behind package ${packageVersion}`);
+  }
+  for (const file of SEARCH_FILES) {
+    try {
+      const bytes = fs.readFileSync(path.join(kbDir, file));
+      result.searchFiles[file] = { bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') };
+      if (!bytes.length) result.issues.push(`search executable ${file} is empty`);
+    } catch { result.issues.push(`search executable ${file} is missing`); }
+  }
+  // The installed archive manifest lets doctor detect code drift even if SOURCE's version stayed
+  // unchanged. This is a consistency check, not independent authentication of a local manifest.
+  try {
+    const archive = JSON.parse(fs.readFileSync(path.join(kbDir, 'ARCHIVE-MANIFEST.json'), 'utf8'));
+    if (archive.kind !== 'ruvnet-brain-archive-manifest' || !Array.isArray(archive.files)) {
+      throw new Error('invalid archive manifest shape');
+    }
+    if (version(archive.version) !== result.searchVersion) {
+      result.issues.push('archive manifest and search engine versions differ');
+    }
+    const runtimeFiles = new Set([...SEARCH_FILES, ...archive.files.filter(row => isRuntimeFile(row?.path)).map(row => row.path)]);
+    for (const file of runtimeFiles) {
+      if (typeof file !== 'string' || path.isAbsolute(file) || file.includes('\\')
+        || file.split('/').some(part => !part || part === '.' || part === '..')) {
+        result.issues.push('archive manifest contains an unsafe runtime path');
+        continue;
+      }
+      const rows = archive.files.filter(row => row?.path === file);
+      let actual = result.searchFiles[file];
+      if (!actual) {
+        try {
+          const bytes = fs.readFileSync(path.join(kbDir, file));
+          actual = { bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') };
+          result.searchFiles[file] = actual;
+        } catch { result.issues.push(`runtime file ${file} is missing`); }
+      }
+      if (rows.length !== 1 || !/^[a-f0-9]{64}$/.test(rows[0]?.sha256 || '')
+        || !Number.isSafeInteger(rows[0]?.bytes) || rows[0].bytes < 0) {
+        result.issues.push(`archive manifest has no unique valid identity for ${file}`);
+      } else if (actual && (actual.sha256 !== rows[0].sha256 || actual.bytes !== rows[0].bytes)) {
+        result.issues.push(`search executable ${file} differs from the installed archive manifest`);
+      }
+    }
+  } catch (error) {
+    result.issues.push(`installed archive manifest is missing or unreadable: ${error.message}`);
+  }
+  // These hashes and the local manifest are NOT independent release approval receipts.
+  result.healthy = result.issues.length === 0;
+  return result;
+}
+
+export function classifySmokeEvidence(verification, answer) {
+  if (!verification?.grounded) return { usable: false, reason: verification?.reason || 'citation-not-verified' };
+  const weak = /EVIDENCE:\s*(?:INSUFFICIENT_EVIDENCE|THIN)\b/i.test(answer);
+  if (weak) return { usable: false, reason: 'retrieval-evidence-insufficient' };
+  if (/BUILT\/SHIPPED CLAIM:\s*NOT PROVEN/i.test(answer)) {
+    return { usable: false, reason: 'required-implementation-unproven' };
+  }
+  return { usable: true, reason: null };
+}

package/scripts/prepublication-evidence.mjs

@@ -9,6 +9,7 @@ import { RELEASE_QUALIFICATION_POLICY } from './integration-evidence.mjs';
 import { readCandidateRetrieval } from './staged-host-verifier.mjs';
 import { validateRetrievalCanaryReceipt } from './retrieval-canary.mjs';
 import { payloadIdFor } from './release-payload.mjs';
+import { HOST_WARMUP_TIMEOUT_MS, RELEASE_SEARCH_DEADLINE_MS } from './host-install-matrix.mjs';
 
 const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
 
@@ -95,11 +96,18 @@ export function buildPrepublicationEvidence({
   requireExactSet(host.value.leaves.map(({ name }) => name), ['claude-only', 'codex-only', 'dual-host'], 'candidate host leaves');
   for (const leaf of host.value.leaves) {
     const grounding = leaf.grounding;
+    const warmupGrounding = leaf.warmupGrounding;
     const grounded = grounding && ['repo', 'path', 'file', 'storedPath']
       .every((field) => typeof grounding[field] === 'string' && grounding[field].trim());
+    const warmupGrounded = warmupGrounding && ['repo', 'path', 'file', 'storedPath']
+      .every((field) => typeof warmupGrounding[field] === 'string' && warmupGrounding[field].trim());
+    const selfStoreWarmup = warmupGrounding?.repo === 'ruvnet-brain';
     if (leaf.sha !== sha || leaf.payloadId !== payload.payloadId || leaf.status !== 'completed'
       || leaf.conclusion !== 'success' || leaf.verdict !== 'PASS'
       || leaf.functionalSearch !== true || leaf.searchExit !== 0 || !grounded
+      || !Number.isFinite(leaf.warmupMs) || leaf.warmupMs < 0 || leaf.warmupMs > HOST_WARMUP_TIMEOUT_MS
+      || !warmupGrounded || !selfStoreWarmup
+      || !Number.isFinite(leaf.searchMs) || leaf.searchMs < 0 || leaf.searchMs > RELEASE_SEARCH_DEADLINE_MS
       || leaf.artifactSha256 !== host.value.artifactSha256) {
       throw new Error(`candidate host leaf is not an exact PASS: ${leaf.name || '(missing)'}`);
     }

package/scripts/public-inputs.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath } from 'node:url';
 import { digest, fileIdentity } from './coverage-integrity.mjs';
 import { isPrivate, loadPrivateFence, loadPrivateSlugs, shouldFenceL2 } from './private-fence.mjs';
 import { promoteArtifactSet } from '../kb/incremental-refresh.mjs';
+import { isCapabilityOnly } from '../kb/capability-only.mjs';
 
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX40 = /^[a-f0-9]{40}$/;
@@ -299,7 +300,7 @@ export function materializePublicInputs({ builderRoot = DEFAULT_ROOT, policy = {
   try {
     for (const repo of allRepos) {
       const src = path.join(kb, `${repo}-primer.md`);
-      if (isPrivate(privateSet, repo)) {
+      if (isPrivate(privateSet, repo) || isCapabilityOnly(repo)) {
         excluded.primers.push({ repo, ...excludedIdentity(src) });
         continue;
       }