total-recall-brain 3.41.4 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/model-catalog.mjs

@@ -0,0 +1,195 @@
+/**
+ * Model and benchmark catalog: a projection of real sources, refreshed out of band.
+ * Reads never touch the network and never invent a figure. An unavailable source keeps its
+ * last good data and reports its error; a source never fetched is simply absent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { derivedDir } from './paths.mjs';
+import { findBinary } from './worker.mjs';
+
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/models';
+const AA_URL = 'https://artificialanalysis.ai/api/v2/language/models/free';
+const SWE_PRO_URL = 'https://labs.scale.com/leaderboard/swe_bench_pro_public';
+const TBENCH_URL = 'https://www.tbench.ai/';
+const EMPTY = () => ({ updatedAt: null, source: 'not-synced', harnessModels: {}, sources: {}, pricing: {}, codingIndex: {}, leaderboards: {} });
+
+const catalogFile = () => path.join(derivedDir(), 'model-catalog.json');
+
+export function getModelCatalog() {
+  try {
+    const data = JSON.parse(fs.readFileSync(catalogFile(), 'utf8'));
+    if (data?.sources) return { ...EMPTY(), ...data };
+  } catch { /* not synced yet */ }
+  return EMPTY();
+}
+
+/** Compare names across catalogs: no provider prefix, no effort suffix, no punctuation. */
+export function normalizeModelName(name) {
+  return String(name).toLowerCase().split('/').pop().replace(/\([^)]*\)/g, ' ').replace(/[-_ ](low|medium|high|xhigh|max)\s*$/, '').replace(/[^a-z0-9]/g, '');
+}
+
+export function parseOpenRouter(json) {
+  const pricing = {};
+  for (const model of json?.data || []) {
+    const prompt = Number(model.pricing?.prompt), completion = Number(model.pricing?.completion);
+    if (!Number.isFinite(prompt) || !Number.isFinite(completion)) continue;
+    pricing[normalizeModelName(model.id)] = { id: model.id, promptPer1M: +(prompt * 1e6).toFixed(4), completionPer1M: +(completion * 1e6).toFixed(4), contextWindow: model.context_length ?? null };
+  }
+  return pricing;
+}
+/** The free tier fills only some indices, so each stays null unless the provider returned it. */
+export function parseArtificialAnalysis(json) {
+  const index = {};
+  for (const model of json?.data || []) {
+    const e = model.evaluations || {};
+    const row = { name: model.name, intelligenceIndex: e.artificial_analysis_intelligence_index ?? null, engineeringIndex: e.artificial_analysis_engineering_index ?? null, codingIndex: e.artificial_analysis_coding_index ?? null, agenticIndex: e.artificial_analysis_agentic_index ?? null };
+    if ([row.intelligenceIndex, row.engineeringIndex, row.codingIndex, row.agenticIndex].some(value => typeof value === 'number')) index[normalizeModelName(model.slug || model.name)] = row;
+  }
+  return index;
+}
+/** Server-rendered rows read: rank, model, score, ±, confidence interval. */
+export function parseSweBenchPro(html) {
+  const text = String(html).replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/g, ' ').replace(/<[^>]+>/g, '|').replace(/\s*\|[\s|]*/g, '|');
+  return [...text.matchAll(/\|(\d{1,3})\|([^|]{2,80})(?:\|[A-Z]{2,8})?\|(\d{1,3}\.\d+)\|±\|(\d{1,3}\.\d+)(?=\|)/g)].map(m => ({ rank: +m[1], model: m[2].replace(/\*$/, '').trim(), score: +m[3], ci95: +m[4] }));
+}
+/** The page embeds its leaderboard as escaped JSON: a `leaderboard` with a version name, then a `rows` array. */
+export function parseTerminalBench(html) {
+  const text = String(html).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  const start = text.indexOf('"rows":[');
+  if (start < 0) return { benchmark: null, rows: [] };
+  const open = start + '"rows":'.length;
+  let depth = 0, inString = false, end = -1;
+  for (let i = open; i < text.length; i += 1) {
+    const c = text[i];
+    if (inString) { if (c === '\\') i += 1; else if (c === '"') inString = false; continue; }
+    if (c === '"') inString = true;
+    else if (c === '[' || c === '{') depth += 1;
+    else if (c === ']' || c === '}') { depth -= 1; if (depth === 0) { end = i; break; } }
+  }
+  if (end < 0) return { benchmark: null, rows: [] };
+  const plain = value => (typeof value === 'string' ? value : value?.label ?? null);
+  const rows = JSON.parse(text.slice(open, end + 1)).map(row => ({
+    rank: row.rank ?? null, model: plain(row.metadata?.model_display), agent: plain(row.metadata?.agent_display), effort: row.metadata?.reasoning_effort ?? null,
+    score: row.metrics?.accuracy ?? null, ci95: row.metrics?.accuracy_ci95_half_width ?? null, costUSD: row.metrics?.total_cost_usd ?? null,
+  })).filter(row => row.model && typeof row.score === 'number');
+  const version = [...text.slice(0, start).matchAll(/"name":"(\d+)-(\d+)-(\d+)"/g)].at(-1);
+  return { benchmark: version ? `${version[1]}.${version[2]}` : null, rows };
+}
+
+async function fromSource(previous, name, url, load, count) {
+  try {
+    const data = await load();
+    const size = count(data);
+    if (!size) throw new Error('Source returned no parseable rows');
+    return { data, status: { ok: true, url, fetchedAt: new Date().toISOString(), count: size } };
+  } catch (error) {
+    return { data: null, status: { ...(previous.sources?.[name] || {}), ok: false, url, attemptedAt: new Date().toISOString(), error: String(error.message).slice(0, 300) } };
+  }
+}
+
+/** Ask each installed harness for its own model list. One failing does not hide the others. */
+function harnessModelList(run) {
+  const readers = {
+    agy: ['agy', ['models'], text => text.split('\n').map(line => line.split('\t')).filter(parts => parts.length === 2).map(([id, name]) => ({ id: id.trim(), name: name.trim() }))],
+    ollama: ['ollama', ['list'], text => text.split('\n').slice(1).map(line => line.trim().split(/\s+/)[0]).filter(id => id && !/embed|bge-|minilm|rerank/i.test(id)).map(id => ({ id, name: id }))],
+    codex: ['codex', ['debug', 'models'], text => (JSON.parse(text).models || []).map(model => ({ id: model.slug, name: model.display_name || model.slug }))],
+  };
+  const models = {}, errors = {};
+  for (const [harness, [bin, args, parse]] of Object.entries(readers)) {
+    const binary = findBinary(bin);
+    if (!binary) continue;
+    try { models[harness] = parse(run(binary, args)); } catch (error) { errors[harness] = String(error.message).slice(0, 200); }
+  }
+  return { models, errors };
+}
+
+function secretFrom(names) {
+  for (const name of names) {
+    try {
+      const value = execFileSync(process.env.TOTAL_RECALL_BIN || 'total-recall', ['auth', 'secret', 'get', name], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (value) return value;
+    } catch { /* try the next name */ }
+  }
+  return null;
+}
+
+export async function syncModelCatalog({ fetchImpl = fetch, secret = secretFrom, run = (bin, args) => execFileSync(bin, args, { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] }) } = {}) {
+  const previous = getModelCatalog();
+  const next = { ...previous, sources: { ...previous.sources } };
+  const getJson = async (url, headers = {}) => {
+    const response = await fetchImpl(url, { headers, signal: AbortSignal.timeout(30000) });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return response.json();
+  };
+  const getText = async url => {
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(30000) });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return response.text();
+  };
+  const apply = (name, key, outcome) => { next.sources[name] = outcome.status; if (outcome.data) next[key] = outcome.data; };
+
+  apply('openrouter', 'pricing', await fromSource(previous, 'openrouter', OPENROUTER_URL, async () => parseOpenRouter(await getJson(OPENROUTER_URL)), data => Object.keys(data).length));
+  apply('artificialAnalysis', 'codingIndex', await fromSource(previous, 'artificialAnalysis', AA_URL, async () => {
+    const key = secret(['DEVELOPER_ARTIFICIAL_ANALYSIS_API_KEY', 'ARTIFICIAL_ANALYSIS_API_KEY']);
+    if (!key) throw new Error('No Artificial Analysis key in the auth store');
+    const rows = {};
+    for (let page = 1, more = true; more && page <= 20; page += 1) {
+      const json = await getJson(`${AA_URL}?page=${page}`, { 'x-api-key': key });
+      Object.assign(rows, parseArtificialAnalysis(json));
+      more = json.pagination?.has_more === true;
+    }
+    return rows;
+  }, data => Object.keys(data).length));
+  next.sources.artificialAnalysis.attribution = 'Data from Artificial Analysis (artificialanalysis.ai)';
+
+  const swe = await fromSource(previous, 'sweBenchPro', SWE_PRO_URL, async () => parseSweBenchPro(await getText(SWE_PRO_URL)), rows => rows.length);
+  next.sources.sweBenchPro = swe.status;
+  const terminal = await fromSource(previous, 'terminalBench', TBENCH_URL, async () => parseTerminalBench(await getText(TBENCH_URL)), parsed => parsed.rows.length);
+  next.sources.terminalBench = { ...terminal.status, ...(terminal.data ? { benchmark: terminal.data.benchmark } : {}) };
+  next.leaderboards = { sweBenchPro: swe.data || previous.leaderboards?.sweBenchPro || [], terminalBench: terminal.data?.rows || previous.leaderboards?.terminalBench || [] };
+
+  const { models, errors } = harnessModelList(run);
+  next.harnessModels = { ...previous.harnessModels, ...models };
+  const failures = Object.entries(errors).map(([harness, error]) => `${harness}: ${error}`).join('; ');
+  next.sources.harnesses = { ok: !failures, fetchedAt: new Date().toISOString(), count: Object.values(next.harnessModels).flat().length, ...(failures ? { error: failures } : {}) };
+  next.updatedAt = new Date().toISOString();
+  next.source = 'sync';
+  saveCatalog(next);
+  const failed = Object.entries(next.sources).filter(([, status]) => !status.ok).map(([name, status]) => ({ source: name, error: status.error }));
+  return { ok: failed.length === 0, sources: next.sources, failed };
+}
+
+/** Attach only figures whose normalized names match. Nothing is estimated for a model without a match. */
+export function joinHarnessModels(catalog = getModelCatalog()) {
+  const rows = [];
+  // Boards list a model once per effort or agent, best first, so the first row is its best result.
+  const board = list => {
+    const rows = new Map();
+    for (const row of list || []) { const key = normalizeModelName(row.model); if (!rows.has(key)) rows.set(key, row); }
+    return rows;
+  };
+  const swe = board(catalog.leaderboards?.sweBenchPro), terminal = board(catalog.leaderboards?.terminalBench);
+  // A board may drop the vendor ("Opus 5.5" for claude-opus-5-5). A suffix of at least five characters still names one model.
+  const lookup = (rows, key) => rows.get(key) || [...rows].find(([name]) => name.length >= 5 && key.endsWith(name))?.[1] || null;
+  for (const [harness, models] of Object.entries(catalog.harnessModels || {})) for (const model of models) {
+    const key = normalizeModelName(model.id);
+    const pricing = catalog.pricing?.[key] || null, index = catalog.codingIndex?.[key] || null;
+    rows.push({ harness, id: model.id, name: model.name, pricing, intelligenceIndex: index?.intelligenceIndex ?? null, engineeringIndex: index?.engineeringIndex ?? null, codingIndex: index?.codingIndex ?? null, agenticIndex: index?.agenticIndex ?? null, sweBenchPro: lookup(swe, key)?.score ?? null, terminalBench: lookup(terminal, key)?.score ?? null });
+  }
+  return rows;
+}
+
+export function saveCatalog(catalog) {
+  fs.mkdirSync(path.dirname(catalogFile()), { recursive: true });
+  const temporary = `${catalogFile()}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(catalog, null, 2));
+  fs.renameSync(temporary, catalogFile());
+  const cell = value => value ?? '-';
+  const lines = ['# Fleet Model Catalog', '', `Updated: ${catalog.updatedAt}`, '', '## Sources', ''];
+  for (const [name, status] of Object.entries(catalog.sources)) lines.push(`- **${name}**: ${status.ok ? `ok, ${status.count} rows, ${status.fetchedAt}` : `failed: ${status.error}`}${status.url ? ` (${status.url})` : ''}${status.attribution ? `. ${status.attribution}` : ''}`);
+  lines.push('', '## Harness models', '', '| Harness | Model | Input / Output per 1M | Intelligence index | Engineering index | SWE-bench Pro | Terminal-Bench |', '| :--- | :--- | :--- | :--- | :--- | :--- | :--- |');
+  for (const row of joinHarnessModels(catalog)) lines.push(`| ${row.harness} | \`${row.id}\` | ${row.pricing ? `$${row.pricing.promptPer1M} / $${row.pricing.completionPer1M}` : '-'} | ${cell(row.intelligenceIndex)} | ${cell(row.engineeringIndex)} | ${cell(row.sweBenchPro)} | ${cell(row.terminalBench)} |`);
+  fs.writeFileSync(path.join(path.dirname(catalogFile()), 'MODELS.md'), lines.join('\n') + '\n');
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/paths.mjs

@@ -0,0 +1,11 @@
+/** Every persistent path resolves here, at call time, so an isolated environment reaches no live store. */
+import os from 'node:os';
+import path from 'node:path';
+
+export function brainDir(env = process.env) {
+  return env.TR_SECRETS_BRAIN || path.join(env.AGENT_DIR || path.join(env.HOME || os.homedir(), '.agent'), 'skills/total-recall');
+}
+export const configDir = (env = process.env) => path.join(brainDir(env), 'config', 'meta-harness');
+export const derivedDir = (env = process.env) => path.join(brainDir(env), 'memory-derived', 'meta-harness');
+export const threadsFile = (env = process.env) => path.join(brainDir(env), 'config', 'meta-harness-threads.json');
+export const receiptsFile = (env = process.env) => path.join(configDir(env), 'runs.jsonl');

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/pool.mjs

@@ -0,0 +1,36 @@
+/** The harnesses that can actually take work right now, and why the others cannot. */
+import { ADAPTER_CATALOG } from '../capability/index.mjs';
+import { inspectAgents, getActiveAdapters } from './worker.mjs';
+import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
+import { measuredWalls } from './telemetry.mjs';
+
+const describe = (id, extra = {}) => {
+  const cap = ADAPTER_CATALOG[id] || {};
+  const spec = getActiveAdapters().find(a => a.id === id) || {};
+  return { id, name: cap.name || spec.name || id, family: cap.family || spec.family || 'custom', tier: cap.tier || spec.tier || 'budget', qualityScore: cap.qualityScore ?? spec.qualityScore ?? 6, costScore: cap.costScore ?? spec.costScore ?? 4, ...extra };
+};
+
+export function exclusionReason(agent, wall, credentialBlock) {
+  if (!agent.installed) return 'not installed';
+  if (!agent.versionVerified) return 'did not report a version';
+  if (agent.authenticated === false) return 'not signed in';
+  if (agent.blockedBy === 'no-chat-model') return 'no chat model installed';
+  if (wall) return `out of quota until ${wall.until}`;
+  if (credentialBlock) return `missing credential: ${String(credentialBlock.message || '').slice(0, 160)}`;
+  return null;
+}
+
+/** An explicit list is the caller's decision and is not filtered. */
+export async function resolvePool({ availableHarnesses, inspect = inspectAgents, receipts = readReceipts } = {}) {
+  if (Array.isArray(availableHarnesses) && availableHarnesses.length) return { ready: availableHarnesses.map(id => describe(id)), excluded: [], walls: {} };
+  const [{ agents = [] }, entries] = await Promise.all([inspect({ env: process.env }), receipts()]);
+  const walls = { ...activeQuotaWalls(entries), ...measuredWalls() };
+  const blocks = activeCredentialBlocks(entries);
+  const ready = [], excluded = [];
+  for (const agent of agents) {
+    const reason = exclusionReason(agent, walls[agent.id], blocks[agent.id]);
+    if (!reason) ready.push(describe(agent.id, { authVerified: agent.authenticated === true }));
+    else if (agent.installed) excluded.push({ harness: agent.id, reason });
+  }
+  return { ready, excluded, walls };
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/review.mjs

@@ -0,0 +1,169 @@
+/**
+ * Meta Harness Universal Cross-Model Adversarial Code Review Engine
+ *
+ * Runs automated code reviews across integrated agent platforms (claude, codex, agy,
+ * grok, dsh, hermes, etc.).
+ *
+ * Golden Rule: The Reviewer MUST belong to a distinct model family from the Author / Implementer
+ * to eliminate self-confirmation bias.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { ADAPTER_CATALOG } from '../capability/index.mjs';
+import { appendThreadTurn, updateThread } from './threads.mjs';
+import { notifyAlert } from './alerts.mjs';
+import { dispatchWithReceipt } from './dispatch.mjs';
+import { resolvePool } from './pool.mjs';
+import { lastJsonWith } from './json-reply.mjs';
+
+const MAX_DIFF = 30000;
+// Generated surfaces say nothing a reviewer can act on, and they crowd out the source.
+const GENERATED = ['.cursorrules', '.cursor', 'openwiki', 'package-lock.json', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'INSTRUCTIONS.md'].map(item => `:!${item}`);
+
+/**
+ * Read exactly what was asked for: an explicit target, the staged changes, or by default the
+ * branch against the default branch and then the uncommitted changes. An explicitly requested
+ * selection that turns out empty stays empty.
+ */
+export function extractGitDiff(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const read = (args, extra = []) => spawnSync('git', ['diff', ...extra, ...args, '--', '.', ...GENERATED], { cwd, encoding: 'utf8', timeout: 15000, maxBuffer: 64 * 1024 * 1024 });
+  const done = (args, diff, target) => {
+    const stat = read(args, ['--stat']).stdout || '';
+    const untracked = spawnSync('git', ['ls-files', '-o', '--exclude-standard'], { cwd, encoding: 'utf8', timeout: 15000 }).stdout || '';
+    return { ok: true, diff, target, stat: stat.trim(), untracked: untracked.trim().split('\n').filter(Boolean) };
+  };
+  const explicit = options.staged === true ? ['--staged'] : (options.target || options.branch) ? [options.target || options.branch] : null;
+  try {
+    if (explicit) {
+      const result = read(explicit);
+      if (result.status !== 0) return { ok: false, error: String(result.stderr || 'git diff failed').trim(), diff: '' };
+      return done(explicit, result.stdout.trim(), explicit.join(' '));
+    }
+    const branchRange = `${getDefaultBranch(cwd)}...HEAD`;
+    const branch = read([branchRange]);
+    if (branch.status === 0 && branch.stdout.trim()) return done([branchRange], branch.stdout.trim(), branchRange);
+    const working = read(['HEAD']);
+    if (working.status !== 0) return { ok: false, error: String(working.stderr || 'git diff failed').trim(), diff: '' };
+    return done(['HEAD'], working.stdout.trim(), 'HEAD');
+  } catch (error) {
+    return { ok: false, error: error.message, diff: '' };
+  }
+}
+
+function getDefaultBranch(cwd) {
+  try {
+    const res = spawnSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], { cwd, encoding: 'utf8', timeout: 3000 });
+    if (res.status === 0 && res.stdout.includes('/')) {
+      return res.stdout.trim().split('/').pop();
+    }
+  } catch {}
+  return 'main';
+}
+
+/**
+ * Assign an adversarial reviewer from an alternative model family
+ */
+export function selectAdversarialReviewer(authorHarness, availablePool = [], options = {}) {
+  const authorFamily = ADAPTER_CATALOG[authorHarness]?.family || null;
+
+  // Filter pool for distinct family
+  const distinctFamilyCandidates = availablePool.filter(h => {
+    const spec = ADAPTER_CATALOG[h.id] || h;
+    return spec.family && spec.family !== authorFamily && h.id !== authorHarness;
+  });
+
+  if (distinctFamilyCandidates.length > 0) {
+    // Prefer higher quality frontier reviewers
+    distinctFamilyCandidates.sort((a, b) => (b.qualityScore || 8) - (a.qualityScore || 8));
+    return distinctFamilyCandidates[0];
+  }
+
+  // Nobody independent is available when every remaining harness shares the author's family.
+  return null;
+}
+
+/**
+ * Construct structured adversarial review prompt
+ */
+export function buildReviewPrompt(diff, context = {}) {
+  const task = context.task ? `Context / Task:\n${context.task}\n\n` : '';
+  const branch = context.branch ? `Branch: ${context.branch}\n` : '';
+
+  return `[ROLE: ADVERSARIAL CODE REVIEWER]
+You are an independent, highly critical senior security and architecture engineer performing an adversarial code review.
+You did NOT write this code. Do not rubber-stamp. Look for vulnerabilities, silent failures, regressions, anti-patterns, and test coverage gaps.
+
+${task}${branch}${context.stat ? `Files changed:\n${context.stat}\n\n` : ''}${context.untracked?.length ? `New untracked files, not in the diff; read them too:\n${context.untracked.slice(0, 100).join('\n')}\n\n` : ''}${diff.length > MAX_DIFF ? `This diff is cut at ${MAX_DIFF} of ${diff.length} characters. Read the remainder from the repository and say so if you could not.\n` : ''}GIT DIFF TO REVIEW:
+\`\`\`diff
+${diff.slice(0, MAX_DIFF)}
+\`\`\`
+
+Evaluate the diff against these strict criteria:
+1. Security & Blast Radius (privilege escalation, token leakage, unhandled exceptions)
+2. Invariant & Rule Adherence (does it break existing contracts or introduce silent side effects?)
+3. Determinism & Test Coverage (are edge cases covered by automated tests?)
+4. Architecture & Code Hygiene (readability, dead code, performance pitfalls)
+
+Output your review in the following exact JSON format:
+{
+  "verdict": "APPROVE" | "REQUEST_CHANGES" | "NEEDS_DISCUSSION",
+  "riskScore": <1-10, where 1 is trivial/clean and 10 is critical vulnerability>,
+  "summary": "<Concise 2-3 sentence executive summary>",
+  "findings": [
+    {
+      "severity": "critical" | "warning" | "suggestion",
+      "file": "<filename>",
+      "line": "<line number or approximate>",
+      "issue": "<concise description>",
+      "suggestedFix": "<concrete recommendation>"
+    }
+  ],
+  "invariantsChecked": ["<list of rules or invariants verified>"]
+}`;
+}
+
+/** Only a stated verdict counts. Anything else needs a human, and says so. */
+export function parseReviewVerdict(response) {
+  const text = String(response || '').trim();
+  const parsed = lastJsonWith(text, 'verdict');
+  if (parsed && ['APPROVE', 'REQUEST_CHANGES', 'NEEDS_DISCUSSION'].includes(parsed.verdict)) return { ...parsed, parsed: true, findings: Array.isArray(parsed.findings) ? parsed.findings : [] };
+  return { verdict: 'NEEDS_DISCUSSION', parsed: false, riskScore: null, summary: text.slice(0, 300) || 'The reviewer returned nothing readable.', findings: [] };
+}
+
+export async function executeCodeReview(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const author = options.author || null;
+  const diffResult = extractGitDiff({ cwd, target: options.target, staged: options.staged });
+  if (!diffResult.ok) throw new Error(`Failed to read the diff: ${diffResult.error}`);
+  if (!diffResult.diff) return { ok: true, verdict: 'NO_DIFF', target: diffResult.target, summary: `Nothing to review for ${diffResult.target}.` };
+
+  const { ready, excluded } = await resolvePool(options);
+  const reviewer = options.reviewer ? (ready.find(h => h.id === options.reviewer) || { id: options.reviewer, name: options.reviewer }) : selectAdversarialReviewer(author, ready);
+  if (!reviewer) throw new Error(`No independent reviewer can take work right now: ${excluded.map(e => `${e.harness} (${e.reason})`).join(', ') || 'no other harness available'}`);
+
+  const authorFamily = ADAPTER_CATALOG[author]?.family || null;
+  const reviewerFamily = ADAPTER_CATALOG[reviewer.id]?.family || reviewer.family || null;
+  if (author && (reviewer.id === author || (authorFamily && authorFamily === reviewerFamily))) throw new Error(`${reviewer.id} shares a model family with the author ${author}, so it cannot review this independently`);
+  const independence = author ? 'verified' : 'unverified: the author was not named';
+  const truncated = diffResult.diff.length > MAX_DIFF;
+  const result = await dispatchWithReceipt({
+    agent: reviewer.id, cwd, contextTask: options.task || `Review the code changes in ${diffResult.target}`,
+    prompt: buildReviewPrompt(diffResult.diff, { task: options.task, branch: options.branch || diffResult.target, stat: diffResult.stat, untracked: diffResult.untracked }),
+    permissions: { read: true, write: false }, allowUnknownAuth: true,
+  }, { dispatchFn: options.dispatchFn, role: 'Reviewer' });
+  if (!result.ok) return { ok: false, target: diffResult.target, reviewer: reviewer.id, error: result.error, failureKind: result.failureKind, excluded };
+
+  const review = { ...parseReviewVerdict(result.response), reviewer: reviewer.id, reviewerName: reviewer.name || reviewer.id, author, target: diffResult.target, truncated, independence, timestamp: new Date().toISOString() };
+  let threadError;
+  if (options.threadId) {
+    try {
+      appendThreadTurn(options.threadId, { role: 'reviewer', agent: reviewer.id, content: `[Code review by ${review.reviewerName}]\nVerdict: ${review.verdict}\nRisk: ${review.riskScore ?? 'not stated'}/10\n${review.summary || ''}` });
+      updateThread(options.threadId, { review, status: review.verdict === 'APPROVE' ? 'approved' : 'review_pending' });
+    } catch (error) { threadError = error.message; }
+  }
+  if (review.verdict === 'REQUEST_CHANGES' || review.riskScore >= 7) {
+    await notifyAlert({ title: `Code review: changes requested by ${review.reviewerName}`, message: `Risk ${review.riskScore ?? 'not stated'}/10 on ${diffResult.target}: ${String(review.summary || '').slice(0, 120)}`, severity: 'warning' });
+  }
+  return { ok: true, review, ...(threadError ? { threadError } : {}) };
+}