@claude-flow/cli 3.16.3 → 3.18.0

package/plugins/ruflo-metaharness/scripts/_invoke.mjs

@@ -0,0 +1,231 @@
+// _invoke.mjs — shared subprocess/plumbing layer for the metaharness plugin family.
+//
+// Extracted from the copy-pasted plumbing that had accreted across
+// _harness.mjs / _darwin.mjs / _redblue.mjs / gepa.mjs (converged
+// security/perf/arch review, 2026-07). The four invocation helpers are now
+// thin adapters on top of this module; their exported function signatures
+// are unchanged (~15 scripts import them).
+//
+// WHAT LIVES HERE (the genuinely-shared parts):
+//   - DEGRADED_RX             one superset regex (incl. `npm ERR` — previously
+//                             only _redblue had it) for "upstream unavailable"
+//   - classifyDegraded()      timeout vs not-available distinction, per-package
+//                             reason prefix
+//   - injectJson()            append --json unless caller opted out / present
+//   - parseTrailingJson()     LAST-{...}-block extraction (the _darwin variant;
+//                             the old _harness FIRST-block variant was a live
+//                             bug — a progress line containing `{...}` would
+//                             shadow the final structured result)
+//   - ensureCachedInstall()   one-time `npm install --prefix ~/.ruflo/<name>-cache-<pin>`
+//                             of a PINNED range — generalizes _redblue.mjs /
+//                             gepa.mjs; the versioned dir means pin bumps
+//                             invalidate stale caches automatically
+//   - findLocalPackageDir()   walk-up node_modules resolution so an already
+//                             installed optionalDependency is used for free
+//   - importOptionalLibrary() bare-import → cached-install fallback for
+//                             library entries (gepa) — never throws on absence
+//   - makeDegradedEmitter()   the ADR-150 rule-#3 exit-0 degraded payload
+//
+// WHAT DOES NOT LIVE HERE (the per-consumer parts):
+//   - _redblue's node-direct isMain workaround rationale
+//   - _darwin's async streaming (`onProgress`) for long evolve runs
+//   - _harness's dual-binary (metaharness + harness) resolution
+//
+// TEST SEAMS (used by test-graceful-degradation.mjs so the ADR-150 drill
+// stays meaningful on machines with a warm cache / local install):
+//   - RUFLO_METAHARNESS_CACHE_BASE   overrides ~/.ruflo as the cache root
+//   - RUFLO_METAHARNESS_SKIP_LOCAL=1 disables local node_modules resolution
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const INSTALL_TIMEOUT_MS = 180_000; // npm install can be slow on cold cache
+
+// Superset of the three per-file regexes. `npm ERR` (from _redblue) is
+// included for everyone: an npm-level failure during a cached install or an
+// npx shim means "upstream unavailable", never a ruflo bug.
+export const DEGRADED_RX = /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT|npm ERR/i;
+
+/**
+ * Classify a finished subprocess as degraded or healthy.
+ * `exitCode === null` means the harness killed it (timeout) — that is a
+ * DIFFERENT operational signal from "package not installable", so the two
+ * reasons stay distinct: `<prefix>-timeout` vs `<prefix>-not-available`.
+ */
+export function classifyDegraded(stderr, exitCode, reasonPrefix) {
+  if (exitCode === null) return { degraded: true, reason: `${reasonPrefix}-timeout` };
+  if (DEGRADED_RX.test(stderr || '')) return { degraded: true, reason: `${reasonPrefix}-not-available` };
+  return { degraded: false };
+}
+
+/** Append --json unless the caller opted out or already passed it. */
+export function injectJson(args, wantJson) {
+  if (!wantJson || args.includes('--json')) return [...args];
+  return [...args, '--json'];
+}
+
+/**
+ * Parse the trailing JSON object from mixed stdout. CLIs in this family emit
+ * human-readable progress first and a structured JSON object LAST — so grab
+ * the last parseable {...} block, falling back to a greedy whole-span match
+ * for nested objects the lazy regex fragments.
+ */
+export function parseTrailingJson(stdout) {
+  const s = stdout || '';
+  const matches = [...s.matchAll(/\{[\s\S]*?\}/g)];
+  for (let i = matches.length - 1; i >= 0; i--) {
+    try { return JSON.parse(matches[i][0]); } catch { /* try previous */ }
+  }
+  const greedy = /\{[\s\S]*\}/.exec(s);
+  if (greedy) { try { return JSON.parse(greedy[0]); } catch { return null; } }
+  return null;
+}
+
+/** Cache root — ~/.ruflo unless the test seam overrides it. */
+export function cacheBaseDir() {
+  return process.env.RUFLO_METAHARNESS_CACHE_BASE || join(homedir(), '.ruflo');
+}
+
+/** Minimal `~X.Y.Z` satisfaction check (no semver dep): same major.minor, patch >= Z. */
+export function satisfiesTildeRange(version, pinVersion) {
+  const pin = /^~(\d+)\.(\d+)\.(\d+)/.exec(String(pinVersion));
+  const ver = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+  if (!pin || !ver) return false;
+  return ver[1] === pin[1] && ver[2] === pin[2] && parseInt(ver[3], 10) >= parseInt(pin[3], 10);
+}
+
+/**
+ * Walk up node_modules from this plugin's directory AND from $CWD looking
+ * for an already-installed copy of `pkg` (e.g. the optionalDependency the
+ * user's ruflo install shipped with). Returns the package dir or null.
+ * When `pinVersion` is given, only a copy satisfying the pin is accepted —
+ * a stale major/minor in an ancestor node_modules is skipped, not used.
+ */
+export function findLocalPackageDir(pkg, pinVersion) {
+  if (process.env.RUFLO_METAHARNESS_SKIP_LOCAL === '1') return null;
+  const segments = pkg.split('/');
+  const starts = [dirname(fileURLToPath(import.meta.url)), process.cwd()];
+  const seen = new Set();
+  for (const start of starts) {
+    let dir = start;
+    for (;;) {
+      if (!seen.has(dir)) {
+        seen.add(dir);
+        const candidate = join(dir, 'node_modules', ...segments);
+        const pj = join(candidate, 'package.json');
+        if (existsSync(pj)) {
+          if (!pinVersion) return candidate;
+          try {
+            const version = JSON.parse(readFileSync(pj, 'utf-8')).version;
+            if (satisfiesTildeRange(version, pinVersion)) return candidate;
+          } catch { /* unreadable — keep walking */ }
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+
+/**
+ * One-time versioned cache install of a PINNED range. Generalizes
+ * gepa.mjs:98-121 / _redblue.mjs:72-102. The cache dir is
+ * `<base>/<shortname>-cache-<pin-digits>` (e.g. redblue-cache-0.1.4,
+ * darwin-cache-0.8.0, metaharness-cache-0.3.0) so existing caches created
+ * by the pre-consolidation helpers remain valid, and bumping the pin
+ * invalidates stale installs automatically.
+ *
+ * @param {object} spec
+ * @param {string} spec.pkg          npm package name (may be scoped)
+ * @param {string} spec.pinVersion   tilde range, e.g. '~0.3.0'
+ * @param {string} [spec.cliRelPath] path inside the package that must exist
+ *                                   post-install (also returned as cliPath)
+ * @param {number} [spec.timeoutMs]  install timeout (default 180s)
+ * @returns {{ok:true, cacheDir:string, pkgDir:string, cliPath:string|null} |
+ *           {ok:false, reason:string, stderr?:string, stdout?:string, error?:string}}
+ */
+export function ensureCachedInstall({ pkg, pinVersion, cliRelPath, timeoutMs = INSTALL_TIMEOUT_MS }) {
+  const short = pkg.split('/').pop();
+  const cacheDir = join(cacheBaseDir(), `${short}-cache-${pinVersion.replace(/[~^]/g, '')}`);
+  const pkgDir = join(cacheDir, 'node_modules', ...pkg.split('/'));
+  const cliPath = cliRelPath ? join(pkgDir, cliRelPath) : null;
+  const probe = cliPath ?? join(pkgDir, 'package.json');
+  if (existsSync(probe)) return { ok: true, cacheDir, pkgDir, cliPath };
+  try {
+    mkdirSync(cacheDir, { recursive: true });
+  } catch (e) {
+    return { ok: false, reason: 'cache-dir-create-failed', error: String(e) };
+  }
+  // `npm install --prefix` puts the package in a known location; this both
+  // avoids npx's symlinked bin shim (the _redblue isMain upstream bug) and
+  // removes the per-call registry check that `npx -y pkg@latest` forced.
+  // shell:false; argv only.
+  const r = spawnSync('npm', [
+    'install',
+    '--no-audit', '--no-fund', '--no-package-lock',
+    '--prefix', cacheDir,
+    `${pkg}@${pinVersion}`,
+  ], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    shell: process.platform === 'win32',
+  });
+  if (r.status !== 0 || !existsSync(probe)) {
+    return {
+      ok: false,
+      reason: 'install-failed',
+      stderr: (r.stderr || '').slice(0, 600),
+      stdout: (r.stdout || '').slice(0, 600),
+    };
+  }
+  return { ok: true, cacheDir, pkgDir, cliPath };
+}
+
+/**
+ * Import an optional LIBRARY entry (as opposed to spawning a CLI):
+ *   1. bare `import(specifier)` — free when the optional dep is installed in
+ *      an ancestor node_modules;
+ *   2. versioned cache install + file-URL import of `entryRelPath`.
+ * Returns the module namespace or null. Never throws on absence / stale
+ * installs (ERR_PACKAGE_PATH_NOT_EXPORTED covers pre-subpath versions).
+ */
+export async function importOptionalLibrary({ specifier, pkg, pinVersion, entryRelPath }) {
+  try {
+    return await import(specifier);
+  } catch (e) {
+    const msg = String(e?.message ?? e);
+    const recoverable = /Cannot find (module|package)|ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ERR_PACKAGE_PATH_NOT_EXPORTED|is not defined by "exports"/i;
+    if (!recoverable.test(msg)) throw e;
+  }
+  const r = ensureCachedInstall({ pkg, pinVersion, cliRelPath: entryRelPath });
+  if (!r.ok || !r.cliPath) return null;
+  try {
+    return await import(pathToFileURL(r.cliPath).href);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the per-package `emit*DegradedJsonAndExit(reason)` helper. Emits the
+ * structured degraded payload and exits 0 — ADR-150 architectural constraint
+ * rule #3: ruflo continues to function when MetaHarness is absent.
+ */
+export function makeDegradedEmitter(pkg, pinVersion) {
+  return function emitDegradedAndExit(reason) {
+    const payload = {
+      degraded: true,
+      reason,
+      hint: `Install with \`npm i -D ${pkg}@${pinVersion}\` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install.`,
+      generatedAt: new Date().toISOString(),
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    process.exit(0);
+  };
+}

package/plugins/ruflo-metaharness/scripts/_redblue.mjs

@@ -1,7 +1,10 @@
 // _redblue.mjs — invocation helper for `@metaharness/redblue`.
 //
 // Sibling of `_darwin.mjs` / `_harness.mjs`. Targets the `redblue` binary
-// from the standalone `@metaharness/redblue@~0.1.1` package.
+// from the standalone `@metaharness/redblue@~0.1.4` package. Shared plumbing
+// (degraded classification, versioned cache install, degraded emitter) lives
+// in `_invoke.mjs`; what stays here is the genuinely-redblue part: the
+// node-direct invocation rationale below.
 //
 // Subcommands surfaced (matches redblue 0.1.x):
 //   - `redblue init   [--out redblue.yaml]`
@@ -21,12 +24,13 @@
 // no error. Darwin's CLI doesn't suffer this (calls main() unconditionally).
 //
 // Workaround: install the package once into a ruflo-owned cache dir
-// (~/.ruflo/redblue-cache) and invoke `node <abs_path>/dist/cli/index.js`
-// directly. argv[1] then equals the real path and isMain becomes true.
+// (~/.ruflo/redblue-cache-<pin>, via _invoke.ensureCachedInstall) and invoke
+// `node <abs_path>/dist/cli/index.js` directly. argv[1] then equals the real
+// path and isMain becomes true.
 //
 // Track upstream fix at: github.com/ruvnet/agent-harness-generator/issues
-// (file separately — when fixed, we can drop the cached-install path and
-// go back to the `npx -y -p ...` pattern used by _darwin.mjs).
+// (file separately — when fixed, we could go back to a bin-shim pattern,
+// though the node-direct cached path is now the family-wide standard anyway).
 //
 // CONTRACT (matches runMetaharness/runDarwin):
 //   - returns `{ stdout, stderr, exitCode, durationMs, degraded, reason? }`
@@ -43,63 +47,29 @@
 //   $OPENROUTER_API_KEY which we never inject.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import {
+  classifyDegraded,
+  ensureCachedInstall,
+  makeDegradedEmitter,
+} from './_invoke.mjs';
 
 const DEFAULT_TIMEOUT_MS = 120_000;
-const INSTALL_TIMEOUT_MS = 180_000;  // npm install can be slow on cold cache
 
 // Pinned semver range. Bump in lock-step with optionalDependencies in
 // @claude-flow/cli/package.json + ruflo/package.json.
-const REDBLUE_PIN = '@metaharness/redblue@~0.1.1';
 const REDBLUE_PKG = '@metaharness/redblue';
-const REDBLUE_PIN_VERSION = '~0.1.1';
+const REDBLUE_PIN_VERSION = '~0.1.4';
+const REDBLUE_PIN = `${REDBLUE_PKG}@${REDBLUE_PIN_VERSION}`;
 
-const CACHE_DIR = join(homedir(), '.ruflo', 'redblue-cache');
-const RESOLVED_CLI = join(
-  CACHE_DIR, 'node_modules', '@metaharness', 'redblue', 'dist', 'cli', 'index.js',
-);
+const REASON_PREFIX = 'metaharness-redblue';
 
-const DEGRADED_RX = /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT|npm ERR/i;
-
-function ensureInstalled() {
-  if (existsSync(RESOLVED_CLI)) return { ok: true };
-  try {
-    mkdirSync(CACHE_DIR, { recursive: true });
-  } catch (e) {
-    return { ok: false, reason: 'cache-dir-create-failed', error: String(e) };
-  }
-  // Use `npm install --prefix` so the package lands in a known location;
-  // this avoids npx's symlinked shim entirely (the upstream bin-bootstrap bug).
-  // shell:false; argv only.
-  const r = spawnSync('npm', [
-    'install',
-    '--no-audit', '--no-fund', '--no-package-lock',
-    '--prefix', CACHE_DIR,
-    `${REDBLUE_PKG}@${REDBLUE_PIN_VERSION}`,
-  ], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf-8',
-    timeout: INSTALL_TIMEOUT_MS,
-    shell: process.platform === 'win32',
-  });
-  if (r.status !== 0 || !existsSync(RESOLVED_CLI)) {
-    return {
-      ok: false,
-      reason: 'install-failed',
-      stderr: (r.stderr || '').slice(0, 600),
-      stdout: (r.stdout || '').slice(0, 600),
-    };
-  }
-  return { ok: true };
-}
-
-function classifyDegraded(stderr, exitCode) {
-  if (exitCode === null) return { degraded: true, reason: 'metaharness-redblue-timeout' };
-  if (DEGRADED_RX.test(stderr)) return { degraded: true, reason: 'metaharness-redblue-not-available' };
-  return { degraded: false };
-}
+// Cache dir is versioned by the pin so bumping REDBLUE_PIN_VERSION
+// invalidates stale installs (handled inside ensureCachedInstall). The
+// resolved layout matches the pre-consolidation helper so existing caches
+// keep serving.
+const CLI_REL_PATH = join('dist', 'cli', 'index.js');
 
 /**
  * Sync invocation. `redblue` runs are bounded by `max_cost_usd` and
@@ -111,7 +81,11 @@ export function runRedblue(args, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
   // 1. Ensure redblue is installed in our cache dir (one-time install).
-  const install = ensureInstalled();
+  const install = ensureCachedInstall({
+    pkg: REDBLUE_PKG,
+    pinVersion: REDBLUE_PIN_VERSION,
+    cliRelPath: CLI_REL_PATH,
+  });
   if (!install.ok) {
     return {
       stdout: install.stdout ?? '',
@@ -120,14 +94,14 @@ export function runRedblue(args, opts = {}) {
       durationMs: Date.now() - start,
       degraded: true,
       reason: install.reason === 'install-failed'
-        ? 'metaharness-redblue-not-available'
-        : `metaharness-redblue-${install.reason}`,
+        ? `${REASON_PREFIX}-not-available`
+        : `${REASON_PREFIX}-${install.reason}`,
     };
   }
 
   // 2. Invoke `node <real-path-to-cli> <args>` so upstream's isMain check
   //    succeeds (argv[1] matches import.meta.url).
-  const r = spawnSync('node', [RESOLVED_CLI, ...args], {
+  const r = spawnSync('node', [install.cliPath, ...args], {
     stdio: ['ignore', 'pipe', 'pipe'],
     encoding: 'utf-8',
     timeout: timeoutMs,
@@ -138,7 +112,7 @@ export function runRedblue(args, opts = {}) {
   const durationMs = Date.now() - start;
   const stdout = r.stdout || '';
   const stderr = r.stderr || '';
-  const classified = classifyDegraded(stderr, r.status);
+  const classified = classifyDegraded(stderr, r.status, REASON_PREFIX);
   if (classified.degraded) {
     return {
       stdout, stderr,
@@ -158,19 +132,12 @@ export function runRedblue(args, opts = {}) {
 
 /**
  * Match the existing `emit*DegradedJsonAndExit` shape used by sibling
- * scripts so MCP tool consumers see one contract.
+ * scripts so MCP tool consumers see one contract. Exit 0 — ADR-150
+ * architectural constraint #3.
  */
-export function emitRedblueDegradedJsonAndExit(reason) {
-  const payload = {
-    degraded: true,
-    reason,
-    hint: 'Install with `npm i -D ' + REDBLUE_PIN + '` or run `npx -y ' + REDBLUE_PIN + ' --help` to verify network access.',
-    generatedAt: new Date().toISOString(),
-  };
-  console.log(JSON.stringify(payload, null, 2));
-  // Exit 0 — ADR-150 architectural constraint #3.
-  process.exit(0);
-}
+export const emitRedblueDegradedJsonAndExit = makeDegradedEmitter(REDBLUE_PKG, REDBLUE_PIN_VERSION);
 
 export const REDBLUE_VERSION_PIN = REDBLUE_PIN;
-export const REDBLUE_CACHE_DIR = CACHE_DIR;
+export const REDBLUE_CACHE_DIR = join(
+  homedir(), '.ruflo', `redblue-cache-${REDBLUE_PIN_VERSION.replace(/[~^]/g, '')}`,
+);

package/plugins/ruflo-metaharness/scripts/evolve.mjs

@@ -24,6 +24,23 @@
 //   node scripts/evolve.mjs --repo . --confirm --generations 5 --children 3
 //   node scripts/evolve.mjs --repo . --confirm --sandbox mock              # no real tests
 //   node scripts/evolve.mjs --repo . --confirm --selection pareto
+//   node scripts/evolve.mjs --repo . --confirm --diagnose                  # + GEPA failure diagnosis
+//
+// --diagnose (GEPA failure diagnosis — the natural-language-diagnosis trick
+// from GEPA, scoped modestly): after the evolve run completes, the losing /
+// failed variants' transcripts are run through darwin's gepa
+// `analyzeTranscript` + `classifyFailure` ops and a `diagnosis` section
+// (failure classes + counts + dominant class per variant) is appended to the
+// emitted JSON report. UPSTREAM SHAPE NOTE (verified against darwin 0.8.0):
+// `metaharness-darwin evolve --json` emits a TEXT leaderboard on stdout — no
+// JSON, no transcripts. The per-variant run records live at
+// `<repo>/.metaharness/runs/<id>.json` as sandbox exec traces
+// ({taskId, exitCode, stdout, stderr}), which are NOT gepa {actionRaw, obs}
+// transcripts. So the diagnosis layer (a) uses gepa-shaped transcripts when
+// a run record embeds them (agent-sandbox / future upstream), (b) falls back
+// to the champion's transcript, and (c) otherwise emits
+// `diagnosis: {available: false, reason, traceSummary}` with a mechanical
+// per-variant trace summary — it NEVER fails the run.
 //
 // EXIT CODES
 //   0  evolved OK (or dry-run, or degraded — MetaHarness Darwin not available)
@@ -31,9 +48,9 @@
 //   2  config error or evolution failure
 //   99 reserved — upstream "safety-disqualified" (propagated)
 
-import { runDarwinAsync, emitDarwinDegradedJsonAndExit } from './_darwin.mjs';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { runDarwinAsync, emitDarwinDegradedJsonAndExit, importGepa } from './_darwin.mjs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
 const ARGS = (() => {
   const a = {
@@ -56,6 +73,7 @@ const ARGS = (() => {
     ruvllmModel: null,
     confirm: false,
     alertOnNoImprovement: false,
+    diagnose: false,
     format: 'json',
     timeoutMs: null,  // computed below if unset
   };
@@ -80,6 +98,7 @@ const ARGS = (() => {
     else if (v === '--ruvllm-model') a.ruvllmModel = process.argv[++i];
     else if (v === '--confirm') a.confirm = true;
     else if (v === '--alert-on-no-improvement') a.alertOnNoImprovement = true;
+    else if (v === '--diagnose') a.diagnose = true;
     else if (v === '--format') a.format = process.argv[++i];
     else if (v === '--timeout-ms') a.timeoutMs = parseInt(process.argv[++i], 10);
   }
@@ -119,6 +138,141 @@ function safetyChecks() {
   return repoPath;
 }
 
+// ---------------------------------------------------------------------------
+// --diagnose support (GEPA failure diagnosis)
+// ---------------------------------------------------------------------------
+
+/** True when `arr` looks like a gepa transcript: [{actionRaw?, obs?}, ...]. */
+function looksLikeGepaTranscript(arr) {
+  return Array.isArray(arr) && arr.length > 0 &&
+    arr.every((e) => e && typeof e === 'object' && ('actionRaw' in e || 'obs' in e));
+}
+
+/**
+ * Pull every gepa-shaped transcript out of one run record. Upstream darwin
+ * 0.8.0 run records carry sandbox exec traces (NOT gepa transcripts), but a
+ * record MAY embed `transcript` arrays (agent sandbox / future upstream) —
+ * accept `record.transcript`, `record.traces[i].transcript`, or `traces`
+ * itself when its entries are {actionRaw, obs}-shaped.
+ */
+function extractGepaTranscripts(record) {
+  const out = [];
+  if (looksLikeGepaTranscript(record?.transcript)) {
+    out.push({ taskId: null, exitCode: null, entries: record.transcript });
+  }
+  const traces = Array.isArray(record?.traces) ? record.traces : [];
+  if (looksLikeGepaTranscript(traces)) {
+    out.push({ taskId: null, exitCode: null, entries: traces });
+  } else {
+    for (const t of traces) {
+      if (looksLikeGepaTranscript(t?.transcript)) {
+        out.push({ taskId: t.taskId ?? null, exitCode: t.exitCode ?? null, entries: t.transcript });
+      }
+    }
+  }
+  return out;
+}
+
+/** Mechanical per-variant summary of sandbox exec traces (the always-available fallback signal). */
+function summarizeTraces(record) {
+  const traces = Array.isArray(record?.traces) ? record.traces : [];
+  return {
+    tasks: traces.length,
+    failed: traces.filter((t) => t?.exitCode !== 0).length,
+    timedOut: traces.filter((t) => t?.timedOut === true).length,
+    blockedActions: traces.reduce((n, t) => n + (Array.isArray(t?.blockedActions) ? t.blockedActions.length : 0), 0),
+  };
+}
+
+/**
+ * Build the `diagnosis` section for the emitted report. Never throws and
+ * never affects the run's exit code — any internal failure degrades to
+ * `{available: false, reason}`.
+ */
+async function buildDiagnosis(repoPath) {
+  try {
+    const metaDir = join(repoPath, '.metaharness');
+    const runsDir = join(metaDir, 'runs');
+    if (!existsSync(runsDir)) {
+      return { available: false, reason: 'no-run-records: <repo>/.metaharness/runs does not exist' };
+    }
+    let winnerId = null;
+    try {
+      winnerId = JSON.parse(readFileSync(join(metaDir, 'reports', 'winner.json'), 'utf-8'))?.variant?.id ?? null;
+    } catch { /* winner unknown — treat all variants as candidates */ }
+
+    const records = [];
+    for (const f of readdirSync(runsDir).filter((f) => f.endsWith('.json')).slice(0, 100)) {
+      try {
+        records.push({ id: f.replace(/\.json$/, ''), rec: JSON.parse(readFileSync(join(runsDir, f), 'utf-8')) });
+      } catch { /* skip unreadable record */ }
+    }
+    if (records.length === 0) {
+      return { available: false, reason: 'no-run-records: <repo>/.metaharness/runs contains no parseable records' };
+    }
+
+    // Losing/failed variants are the primary diagnosis targets; the champion
+    // is the fallback when no loser exposes a transcript.
+    const losers = records.filter((r) =>
+      r.id !== winnerId &&
+      (r.rec?.score?.promoted === false ||
+       (Array.isArray(r.rec?.traces) && r.rec.traces.some((t) => t?.exitCode !== 0 || t?.timedOut))));
+    const champion = records.filter((r) => r.id === winnerId);
+
+    let scope = 'losing-variants';
+    let pool = losers.map((r) => ({ ...r, transcripts: extractGepaTranscripts(r.rec) }))
+      .filter((r) => r.transcripts.length > 0);
+    if (pool.length === 0) {
+      scope = 'champion-fallback';
+      pool = champion.map((r) => ({ ...r, transcripts: extractGepaTranscripts(r.rec) }))
+        .filter((r) => r.transcripts.length > 0);
+    }
+
+    if (pool.length === 0) {
+      // Verified upstream shape (darwin 0.8.0): run records are sandbox exec
+      // traces, not gepa transcripts. Emit the mechanical trace summary so
+      // --diagnose still yields signal.
+      const target = losers.length ? losers : records;
+      return {
+        available: false,
+        reason: 'no-gepa-transcripts: run records contain sandbox exec traces ({taskId, exitCode, stdout, stderr}), not gepa {actionRaw, obs} transcripts',
+        traceSummary: Object.fromEntries(target.map((r) => [r.id, summarizeTraces(r.rec)])),
+      };
+    }
+
+    const gepa = await importGepa();
+    if (!gepa || typeof gepa.analyzeTranscript !== 'function') {
+      return { available: false, reason: 'metaharness-darwin-gepa-not-available' };
+    }
+
+    const classLabel = (n) => {
+      const raw = gepa.FAILURE_CLASSES?.[n];
+      return raw ? String(raw).split(' (')[0] : `class-${n}`;
+    };
+
+    const totals = {};
+    const variants = [];
+    for (const r of pool) {
+      const classes = {};
+      for (const t of r.transcripts) {
+        const analysis = gepa.analyzeTranscript(t.entries);
+        const cls = typeof gepa.classifyFailure === 'function'
+          ? gepa.classifyFailure({ goldResolved: t.exitCode === 0, analysis })
+          : -1;
+        const label = classLabel(cls);
+        classes[label] = (classes[label] || 0) + 1;
+        totals[label] = (totals[label] || 0) + 1;
+      }
+      const dominantClass = Object.entries(classes).sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+      variants.push({ id: r.id, transcripts: r.transcripts.length, failureClasses: classes, dominantClass });
+    }
+
+    return { available: true, scope, variants, totals };
+  } catch (e) {
+    return { available: false, reason: `diagnosis-failed: ${e?.message ?? e}` };
+  }
+}
+
 // Compute a sensible timeout from the search shape if caller didn't specify.
 // Rough budget: each variant ~= 30s (sandbox test command + safety inspect),
 // total ~= generations × children × per-variant / concurrency.
@@ -146,6 +300,7 @@ async function main() {
     epistasis: ARGS.epistasis,
     curriculum: ARGS.curriculum,
     mutator: ARGS.mutator,
+    diagnose: ARGS.diagnose,
     estVariants: ARGS.generations * ARGS.children,
     timeoutMs: ARGS.timeoutMs ?? defaultTimeoutMs(),
     output: `${repoPath}/.metaharness/{archive.json, lineage.json, variants/, runs/, reports/winner.json}`,
@@ -233,6 +388,11 @@ async function main() {
     generatedAt: new Date().toISOString(),
   };
 
+  // GEPA failure diagnosis — opt-in, additive, never fails the run.
+  if (ARGS.diagnose) {
+    payload.data.diagnosis = await buildDiagnosis(repoPath);
+  }
+
   console.log(JSON.stringify(payload, null, 2));
   if (ARGS.alertOnNoImprovement && noImprovement) process.exit(1);
   process.exit(0);