@claude-flow/cli 3.42.3 → 3.42.5

package/plugins/ruflo-metaharness/agents/metaharness-architect.md

@@ -1,58 +1,58 @@
----
-name: metaharness-architect
-description: MetaHarness integration architect for ruflo. Surfaces score/genome/mint/mcp-scan/threat-model upstream capabilities via skills; enforces ADR-150 architectural constraint (MetaHarness as removable augmentation, never required runtime dep); coordinates Phase 1 MVP rollout
-model: haiku
----
-
-You are the metaharness-architect for ruflo. Your job is to expose the
-`@metaharness/*` ecosystem's capabilities through ruflo's UX while
-keeping ruflo independently operational at all times.
-
-## ADR-150 invariants (load-bearing)
-
-1. **Removable** — `npm ls --without-deps @metaharness/*` must still
-   produce a working CLI.
-2. **Optional in package.json** — every `@metaharness/*` package goes in
-   `optionalDependencies` or `peerDependencies` (optional), NEVER
-   `dependencies`.
-3. **Graceful degradation** — every code path that imports a
-   `@metaharness/*` symbol catches `MODULE_NOT_FOUND` and falls back.
-   The `emitDegradedJsonAndExit()` helper in `scripts/_harness.mjs` is
-   the reference implementation.
-4. **CI gate** — at least one CI job runs ruflo with no MetaHarness
-   packages installed and asserts smoke still passes.
-
-If a PR breaks any of these four rules, it is a breaking change and
-needs its own ADR.
-
-## Skills (6 — what each does, when to invoke)
-
-| Skill | Role | Invoke when |
-|---|---|---|
-| `harness-score` | 5-dim numeric scorecard | Pre-mint readiness check; CI regression gate |
-| `harness-genome` | 7-section categorical report | Pre-mint architecture review; drift detection over time |
-| `harness-mcp-scan` | Static MCP security findings | Every PR; enterprise security review |
-| `harness-threat-model` | Categorized threat report | Pre-launch review; periodic OIA-audit cadence |
-| `harness-oia-audit` | Composite weekly audit worker (iter 7) | Cron-scheduled; bundles oia+threat+mcp into one timestamped record in `metaharness-audit` namespace |
-| `harness-mint` | Scaffold a custom harness | User wants to fork; ALWAYS dry-run first, never write to project root |
-
-## Tools (subprocess-only, no library imports)
-
-- All skills shell out to the pinned `metaharness` / `harness` binaries (`metaharness@~0.3.0`, local install or one-time versioned cache — never `@latest`) via the `_harness.mjs` shared helper.
-- 60s hard timeout per subprocess.
-- Output captured + parsed; `--json` flag forced unless the script opts out.
-- No `@metaharness/*` import statement appears outside the optional-router path in `v3/@claude-flow/cli/src/ruvector/neural-router.ts`.
-
-## Phase tracker
-
-- ✅ Phase 0 — measurement spike (ruflo's own scorecard captured 2026-06-16: harnessFit 82, risk_score 0.27, publish_readiness 0.9)
-- 🔄 Phase 1 — MVP plugin (this commit + CI gates + KRR retraining)
-- ⏳ Phase 2 — Expansion (eject command, SelfEvolvingRouter parallel-log, harness registry, oia-audit worker)
-- ⏳ Phase 3 — Harness Intelligence Layer (each item gets its own ADR)
-
-## Cross-links
-
-- [ADR-150](../../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) — decision
-- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) — phase tracker
-- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) — graded evidence
-- [Upstream](https://github.com/ruvnet/agent-harness-generator) — `metaharness` source
+---
+name: metaharness-architect
+description: MetaHarness integration architect for ruflo. Surfaces score/genome/mint/mcp-scan/threat-model upstream capabilities via skills; enforces ADR-150 architectural constraint (MetaHarness as removable augmentation, never required runtime dep); coordinates Phase 1 MVP rollout
+model: haiku
+---
+
+You are the metaharness-architect for ruflo. Your job is to expose the
+`@metaharness/*` ecosystem's capabilities through ruflo's UX while
+keeping ruflo independently operational at all times.
+
+## ADR-150 invariants (load-bearing)
+
+1. **Removable** — `npm ls --without-deps @metaharness/*` must still
+   produce a working CLI.
+2. **Optional in package.json** — every `@metaharness/*` package goes in
+   `optionalDependencies` or `peerDependencies` (optional), NEVER
+   `dependencies`.
+3. **Graceful degradation** — every code path that imports a
+   `@metaharness/*` symbol catches `MODULE_NOT_FOUND` and falls back.
+   The `emitDegradedJsonAndExit()` helper in `scripts/_harness.mjs` is
+   the reference implementation.
+4. **CI gate** — at least one CI job runs ruflo with no MetaHarness
+   packages installed and asserts smoke still passes.
+
+If a PR breaks any of these four rules, it is a breaking change and
+needs its own ADR.
+
+## Skills (6 — what each does, when to invoke)
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `harness-score` | 5-dim numeric scorecard | Pre-mint readiness check; CI regression gate |
+| `harness-genome` | 7-section categorical report | Pre-mint architecture review; drift detection over time |
+| `harness-mcp-scan` | Static MCP security findings | Every PR; enterprise security review |
+| `harness-threat-model` | Categorized threat report | Pre-launch review; periodic OIA-audit cadence |
+| `harness-oia-audit` | Composite weekly audit worker (iter 7) | Cron-scheduled; bundles oia+threat+mcp into one timestamped record in `metaharness-audit` namespace |
+| `harness-mint` | Scaffold a custom harness | User wants to fork; ALWAYS dry-run first, never write to project root |
+
+## Tools (subprocess-only, no library imports)
+
+- All skills shell out to the pinned `metaharness` / `harness` binaries (`metaharness@~0.3.0`, local install or one-time versioned cache — never `@latest`) via the `_harness.mjs` shared helper.
+- 60s hard timeout per subprocess.
+- Output captured + parsed; `--json` flag forced unless the script opts out.
+- No `@metaharness/*` import statement appears outside the optional-router path in `v3/@claude-flow/cli/src/ruvector/neural-router.ts`.
+
+## Phase tracker
+
+- ✅ Phase 0 — measurement spike (ruflo's own scorecard captured 2026-06-16: harnessFit 82, risk_score 0.27, publish_readiness 0.9)
+- 🔄 Phase 1 — MVP plugin (this commit + CI gates + KRR retraining)
+- ⏳ Phase 2 — Expansion (eject command, SelfEvolvingRouter parallel-log, harness registry, oia-audit worker)
+- ⏳ Phase 3 — Harness Intelligence Layer (each item gets its own ADR)
+
+## Cross-links
+
+- [ADR-150](../../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) — decision
+- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) — phase tracker
+- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) — graded evidence
+- [Upstream](https://github.com/ruvnet/agent-harness-generator) — `metaharness` source

package/plugins/ruflo-metaharness/commands/ruflo-metaharness.md

@@ -1,50 +1,50 @@
----
-name: ruflo-metaharness
-description: MetaHarness integration — score, genome, mint, mcp-scan, threat-model — via subprocess invocations honoring ADR-150 architectural constraint
----
-
-MetaHarness integration commands. All shell out to the PINNED
-`metaharness`/`harness` binaries (`metaharness@~0.3.0` — resolved from a local
-install or a one-time `~/.ruflo/metaharness-cache-<pin>` install, never
-`@latest`) via the `_harness.mjs` shared helper; no library imports on
-ruflo's boot path.
-
-**`harness score [--path .] [--alert-on-fit-below N] [--format table|json]`** -- 5-dimension readiness scorecard (harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady).
-1. Run `node plugins/ruflo-metaharness/scripts/score.mjs --path <dir>`
-2. Output JSON (default) with all dimensions + recommended template + archetype
-3. `--alert-on-fit-below N` exits 1 when harnessFit < N — CI regression gate
-4. Subprocess + 60s hard timeout; graceful degradation when metaharness unavailable
-
-**`harness genome [--path .] [--alert-on-risk-above 0.5] [--format table|json]`** -- 7-section repo readiness report (repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness).
-1. Run `node plugins/ruflo-metaharness/scripts/genome.mjs --path <dir>`
-2. Pairs with harness-score for full readiness view — score is numeric, genome is categorical
-3. `needs-work` and `blocked` are valid reports. JSON includes the upstream
-   `verdict` and `verdictExitCode`; only an invalid/missing report is fatal.
-4. `--alert-on-risk-above N` exits 1 when risk_score > N
-5. Useful for drift detection: snapshot genome over time, diff to spot agent_topology drift
-
-**`harness mcp-scan [--path .] [--fail-on low|medium|high] [--format table|json]`** -- Static security scan of `.mcp/servers.json` + `.harness/claims.json`. Reads only; no dispatch.
-1. Run `node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --path <dir>`
-2. Severity-ranked findings (low/medium/high); default fail-on `high`
-3. CI integration: `mcp-scan --fail-on high` fails the build on any HIGH finding
-4. Pairs with harness-threat-model for enterprise-review-grade categorization
-
-**`harness threat-model [--path .] [--fail-on clean|low|medium|high] [--format table|json]`** -- Enterprise-review threat model. Returns `worst` severity + categorized `findings[]`.
-1. Run `node plugins/ruflo-metaharness/scripts/threat-model.mjs --path <dir>`
-2. Default fail-on `high`; tightenable to `medium` for stricter gates
-3. Output suitable for sharing with security/infosec team
-4. Will be auto-fired by the Phase-2 oia-audit background worker on a schedule
-
-**`harness oia-audit [--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]`** -- Phase-2 composite worker (ADR-150). Bundles oia-manifest + threat-model + mcp-scan into one timestamped audit record, stores in `metaharness-audit` memory namespace.
-1. Run `node plugins/ruflo-metaharness/scripts/oia-audit.mjs`
-2. Composite worst-severity = max(threatModel.worst, mcpScan.findings.severity)
-3. `--alert-on-worst high` exits 1 when composite ≥ high — CI weekly drift gate
-4. `--dry-run` skips memory persistence — useful for local checks
-5. Designed for cron schedule: weekly snapshot enables audit drift tracking via memory diff
-
-**`harness mint --name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]`** -- Scaffold a custom AI agent harness. DRY-RUN by default; --confirm required to write.
-1. Run `node plugins/ruflo-metaharness/scripts/mint.mjs --name <id> --template <id> --host <id>`
-2. **Safety**: refuses to write to the calling repo root or any path inside it; defaults to `/tmp/ruflo-mint-<ts>-<name>/`
-3. Without `--confirm`: prints dry-run plan, exits 0 without touching disk
-4. With `--confirm`: shells `npx metaharness new ... --yes`
-5. Templates: minimal + 19 verticals (coding, devops, support, legal, …). Hosts: claude-code, codex, pi-dev, opencode, github-actions, +4 more.
+---
+name: ruflo-metaharness
+description: MetaHarness integration — score, genome, mint, mcp-scan, threat-model — via subprocess invocations honoring ADR-150 architectural constraint
+---
+
+MetaHarness integration commands. All shell out to the PINNED
+`metaharness`/`harness` binaries (`metaharness@~0.3.0` — resolved from a local
+install or a one-time `~/.ruflo/metaharness-cache-<pin>` install, never
+`@latest`) via the `_harness.mjs` shared helper; no library imports on
+ruflo's boot path.
+
+**`harness score [--path .] [--alert-on-fit-below N] [--format table|json]`** -- 5-dimension readiness scorecard (harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady).
+1. Run `node plugins/ruflo-metaharness/scripts/score.mjs --path <dir>`
+2. Output JSON (default) with all dimensions + recommended template + archetype
+3. `--alert-on-fit-below N` exits 1 when harnessFit < N — CI regression gate
+4. Subprocess + 60s hard timeout; graceful degradation when metaharness unavailable
+
+**`harness genome [--path .] [--alert-on-risk-above 0.5] [--format table|json]`** -- 7-section repo readiness report (repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness).
+1. Run `node plugins/ruflo-metaharness/scripts/genome.mjs --path <dir>`
+2. Pairs with harness-score for full readiness view — score is numeric, genome is categorical
+3. `needs-work` and `blocked` are valid reports. JSON includes the upstream
+   `verdict` and `verdictExitCode`; only an invalid/missing report is fatal.
+4. `--alert-on-risk-above N` exits 1 when risk_score > N
+5. Useful for drift detection: snapshot genome over time, diff to spot agent_topology drift
+
+**`harness mcp-scan [--path .] [--fail-on low|medium|high] [--format table|json]`** -- Static security scan of `.mcp/servers.json` + `.harness/claims.json`. Reads only; no dispatch.
+1. Run `node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --path <dir>`
+2. Severity-ranked findings (low/medium/high); default fail-on `high`
+3. CI integration: `mcp-scan --fail-on high` fails the build on any HIGH finding
+4. Pairs with harness-threat-model for enterprise-review-grade categorization
+
+**`harness threat-model [--path .] [--fail-on clean|low|medium|high] [--format table|json]`** -- Enterprise-review threat model. Returns `worst` severity + categorized `findings[]`.
+1. Run `node plugins/ruflo-metaharness/scripts/threat-model.mjs --path <dir>`
+2. Default fail-on `high`; tightenable to `medium` for stricter gates
+3. Output suitable for sharing with security/infosec team
+4. Will be auto-fired by the Phase-2 oia-audit background worker on a schedule
+
+**`harness oia-audit [--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]`** -- Phase-2 composite worker (ADR-150). Bundles oia-manifest + threat-model + mcp-scan into one timestamped audit record, stores in `metaharness-audit` memory namespace.
+1. Run `node plugins/ruflo-metaharness/scripts/oia-audit.mjs`
+2. Composite worst-severity = max(threatModel.worst, mcpScan.findings.severity)
+3. `--alert-on-worst high` exits 1 when composite ≥ high — CI weekly drift gate
+4. `--dry-run` skips memory persistence — useful for local checks
+5. Designed for cron schedule: weekly snapshot enables audit drift tracking via memory diff
+
+**`harness mint --name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]`** -- Scaffold a custom AI agent harness. DRY-RUN by default; --confirm required to write.
+1. Run `node plugins/ruflo-metaharness/scripts/mint.mjs --name <id> --template <id> --host <id>`
+2. **Safety**: refuses to write to the calling repo root or any path inside it; defaults to `/tmp/ruflo-mint-<ts>-<name>/`
+3. Without `--confirm`: prints dry-run plan, exits 0 without touching disk
+4. With `--confirm`: shells `npx metaharness new ... --yes`
+5. Templates: minimal + 19 verticals (coding, devops, support, legal, …). Hosts: claude-code, codex, pi-dev, opencode, github-actions, +4 more.

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

@@ -1,210 +1,210 @@
-// _darwin.mjs — shared invocation helper for the `@metaharness/darwin` CLI.
-//
-// Mirrors `_harness.mjs` for the umbrella `metaharness` / `harness` binaries,
-// but targets the separate darwin binary (`metaharness-darwin`) which is
-// published as its own npm package (`@metaharness/darwin@~0.8.0`).
-//
-// Shared plumbing (degraded classification, --json injection, trailing-JSON
-// parse, degraded emitter) lives in `_invoke.mjs`. What stays here is the
-// genuinely-darwin part: the ASYNC STREAMING variant (`runDarwinAsync`) that
-// long `evolve` runs need for per-generation progress visibility.
-//
-// Three subcommands surfaced (matches darwin 0.8.x — same verbs as 0.3.x,
-// with GEPA-engine evolve flags added upstream: --selection modes,
-// --crossover, --epistasis, --curriculum, --mutator ruvllm, --sandbox):
-//   - `metaharness-darwin evolve <repo> [...]`         — harness self-improvement
-//   - `metaharness-darwin bench <create|verify> ...`   — bench-suite lifecycle
-//   - `metaharness-darwin security bench [...]`        — Darwin Shield (upstream ADR-155)
-//
-// CONTRACT (identical to runMetaharness/runHarness):
-//   - returns `{ stdout, stderr, exitCode, json|null, durationMs, degraded, reason? }`
-//   - `--json` is appended automatically when `opts.json !== false`
-//   - subprocess hard timeout (default 60s, override with opts.timeoutMs)
-//   - on MODULE_NOT_FOUND / network failure / "not installed", returns
-//     `degraded: true, reason: 'metaharness-darwin-not-available'` — never throws
-//     (ADR-150 graceful-degradation rule #3; ADR-153 §"Architecture" constraint 3)
-//
-// IMPORTANT — evolve has long timeouts:
-//   `evolve` is the only long-running verb in the metaharness family. A real
-//   evolution with --generations 10 --children 5 --concurrency 2 takes
-//   minutes-to-hours, NOT seconds. Callers MUST pass an explicit `timeoutMs`
-//   matched to their --generations × --children × sandbox cost; the 60s
-//   default is for `bench verify` and `security bench --population 2 --cycles 1`
-//   smoke shapes only.
-
-import { spawnSync, spawn } from 'node:child_process';
-import {
-  classifyDegraded,
-  importOptionalLibrary,
-  injectJson,
-  makeDegradedEmitter,
-  parseTrailingJson,
-} from './_invoke.mjs';
-
-const DEFAULT_TIMEOUT_MS = 60_000;
-
-// Pinned semver range. Bump in lock-step with optionalDependencies in
-// @claude-flow/cli/package.json + ruflo/package.json. The `~` allows
-// patch upgrades without re-pinning.
-const DARWIN_PKG = '@metaharness/darwin';
-const DARWIN_PIN_VERSION = '~0.8.0';
-const DARWIN_PIN = `${DARWIN_PKG}@${DARWIN_PIN_VERSION}`;
-
-const REASON_PREFIX = 'metaharness-darwin';
-
-function buildArgv(args, wantJson) {
-  // `metaharness-darwin` historically does NOT take --json on every
-  // subcommand (some emit plain text reports — security bench in
-  // particular is markdown). We still append --json for callers that
-  // explicitly request it, but never silently inject it on subcommands
-  // that don't accept it. The shape that does support --json is the
-  // single-verb `evolve` and `bench verify`.
-  return injectJson(args, wantJson);
-}
-
-// darwin's evolve emits a final JSON object at end of stdout when --json
-// is passed; everything before is human-readable progress. Grab the LAST
-// {...} block, not the first — the first may be a per-generation log line.
-// (This last-block parse is now the family-wide shared implementation.)
-const maybeParseJson = parseTrailingJson;
-
-/**
- * Sync invocation. Use for short subcommands (`bench verify`, smoke shapes).
- * Async variant below for long-running `evolve` calls.
- */
-export function runDarwin(args, opts = {}) {
-  const start = Date.now();
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const wantJson = opts.json !== false;
-  const argv = buildArgv(args, wantJson);
-  const r = spawnSync('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf-8',
-    timeout: timeoutMs,
-    cwd: opts.cwd,
-    env: { ...process.env, ...(opts.env || {}) },
-    shell: process.platform === 'win32',
-  });
-  const durationMs = Date.now() - start;
-  const stdout = r.stdout || '';
-  const stderr = r.stderr || '';
-  const classified = classifyDegraded(stderr, r.status, REASON_PREFIX);
-  if (classified.degraded) {
-    return {
-      stdout, stderr,
-      exitCode: r.status ?? 127,
-      json: null,
-      durationMs,
-      degraded: true,
-      reason: classified.reason,
-    };
-  }
-  return {
-    stdout, stderr,
-    exitCode: r.status ?? 0,
-    json: wantJson ? maybeParseJson(stdout) : null,
-    durationMs,
-    degraded: false,
-  };
-}
-
-/**
- * Async invocation with streaming. Required for `evolve` because the run
- * can take 10+ minutes and the caller wants progress visibility.
- *
- * If `opts.onProgress(line)` is provided, called once per stderr line.
- * darwin writes per-generation progress to stderr, structured result to
- * stdout. Cancellable via opts.signal (AbortSignal).
- */
-export function runDarwinAsync(args, opts = {}) {
-  return new Promise((resolve) => {
-    const start = Date.now();
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const wantJson = opts.json !== false;
-    const argv = buildArgv(args, wantJson);
-    const p = spawn('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      cwd: opts.cwd,
-      env: { ...process.env, ...(opts.env || {}) },
-      shell: process.platform === 'win32',
-    });
-    let stdout = '', stderr = '', stderrBuf = '';
-    p.stdout?.on('data', (d) => { stdout += d.toString(); });
-    p.stderr?.on('data', (d) => {
-      const s = d.toString();
-      stderr += s;
-      if (opts.onProgress) {
-        stderrBuf += s;
-        const lines = stderrBuf.split('\n');
-        stderrBuf = lines.pop() ?? '';
-        for (const line of lines) opts.onProgress(line);
-      }
-    });
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      try { p.kill('SIGTERM'); } catch { /* ignore */ }
-    }, timeoutMs);
-    if (opts.signal) {
-      opts.signal.addEventListener('abort', () => {
-        try { p.kill('SIGTERM'); } catch { /* ignore */ }
-      }, { once: true });
-    }
-    p.on('error', (e) => {
-      clearTimeout(timer);
-      resolve({
-        stdout,
-        stderr: stderr + String(e?.message ?? e),
-        exitCode: 127, json: null, durationMs: Date.now() - start,
-        degraded: true, reason: `${REASON_PREFIX}-not-available`,
-      });
-    });
-    p.on('close', (code) => {
-      clearTimeout(timer);
-      const durationMs = Date.now() - start;
-      const classified = classifyDegraded(stderr, timedOut ? null : code, REASON_PREFIX);
-      if (classified.degraded) {
-        resolve({
-          stdout, stderr,
-          exitCode: code ?? 127, json: null, durationMs,
-          degraded: true, reason: classified.reason,
-        });
-        return;
-      }
-      resolve({
-        stdout, stderr,
-        exitCode: code ?? 0,
-        json: wantJson ? maybeParseJson(stdout) : null,
-        durationMs,
-        degraded: false,
-      });
-    });
-  });
-}
-
-/**
- * Match the existing `emitDegradedJsonAndExit` shape used by the
- * metaharness-umbrella scripts so MCP tool consumers see one contract.
- * Exit 0 — ADR-150 architectural constraint: ruflo continues to function
- * when MetaHarness is absent. Same posture as the umbrella scripts.
- */
-export const emitDarwinDegradedJsonAndExit = makeDegradedEmitter(DARWIN_PKG, DARWIN_PIN_VERSION);
-
-export const DARWIN_VERSION_PIN = DARWIN_PIN;
-
-/**
- * Resolver for the darwin GEPA LIBRARY entry (`@metaharness/darwin/gepa`).
- * Lives here (not in gepa.mjs) because gepa.mjs is a CLI script that runs
- * main() on import — this module is the import-safe home for the darwin
- * pin. Used by gepa.mjs (genome/validate/render/analyze ops) and by
- * evolve.mjs --diagnose (failure-class analysis of run transcripts).
- * Returns the module namespace or null. Never throws on absence.
- */
-export function importGepa() {
-  return importOptionalLibrary({
-    specifier: '@metaharness/darwin/gepa',
-    pkg: DARWIN_PKG,
-    pinVersion: DARWIN_PIN_VERSION,
-    entryRelPath: 'dist/gepa/index.js',
-  });
-}
+// _darwin.mjs — shared invocation helper for the `@metaharness/darwin` CLI.
+//
+// Mirrors `_harness.mjs` for the umbrella `metaharness` / `harness` binaries,
+// but targets the separate darwin binary (`metaharness-darwin`) which is
+// published as its own npm package (`@metaharness/darwin@~0.8.0`).
+//
+// Shared plumbing (degraded classification, --json injection, trailing-JSON
+// parse, degraded emitter) lives in `_invoke.mjs`. What stays here is the
+// genuinely-darwin part: the ASYNC STREAMING variant (`runDarwinAsync`) that
+// long `evolve` runs need for per-generation progress visibility.
+//
+// Three subcommands surfaced (matches darwin 0.8.x — same verbs as 0.3.x,
+// with GEPA-engine evolve flags added upstream: --selection modes,
+// --crossover, --epistasis, --curriculum, --mutator ruvllm, --sandbox):
+//   - `metaharness-darwin evolve <repo> [...]`         — harness self-improvement
+//   - `metaharness-darwin bench <create|verify> ...`   — bench-suite lifecycle
+//   - `metaharness-darwin security bench [...]`        — Darwin Shield (upstream ADR-155)
+//
+// CONTRACT (identical to runMetaharness/runHarness):
+//   - returns `{ stdout, stderr, exitCode, json|null, durationMs, degraded, reason? }`
+//   - `--json` is appended automatically when `opts.json !== false`
+//   - subprocess hard timeout (default 60s, override with opts.timeoutMs)
+//   - on MODULE_NOT_FOUND / network failure / "not installed", returns
+//     `degraded: true, reason: 'metaharness-darwin-not-available'` — never throws
+//     (ADR-150 graceful-degradation rule #3; ADR-153 §"Architecture" constraint 3)
+//
+// IMPORTANT — evolve has long timeouts:
+//   `evolve` is the only long-running verb in the metaharness family. A real
+//   evolution with --generations 10 --children 5 --concurrency 2 takes
+//   minutes-to-hours, NOT seconds. Callers MUST pass an explicit `timeoutMs`
+//   matched to their --generations × --children × sandbox cost; the 60s
+//   default is for `bench verify` and `security bench --population 2 --cycles 1`
+//   smoke shapes only.
+
+import { spawnSync, spawn } from 'node:child_process';
+import {
+  classifyDegraded,
+  importOptionalLibrary,
+  injectJson,
+  makeDegradedEmitter,
+  parseTrailingJson,
+} from './_invoke.mjs';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+// Pinned semver range. Bump in lock-step with optionalDependencies in
+// @claude-flow/cli/package.json + ruflo/package.json. The `~` allows
+// patch upgrades without re-pinning.
+const DARWIN_PKG = '@metaharness/darwin';
+const DARWIN_PIN_VERSION = '~0.8.0';
+const DARWIN_PIN = `${DARWIN_PKG}@${DARWIN_PIN_VERSION}`;
+
+const REASON_PREFIX = 'metaharness-darwin';
+
+function buildArgv(args, wantJson) {
+  // `metaharness-darwin` historically does NOT take --json on every
+  // subcommand (some emit plain text reports — security bench in
+  // particular is markdown). We still append --json for callers that
+  // explicitly request it, but never silently inject it on subcommands
+  // that don't accept it. The shape that does support --json is the
+  // single-verb `evolve` and `bench verify`.
+  return injectJson(args, wantJson);
+}
+
+// darwin's evolve emits a final JSON object at end of stdout when --json
+// is passed; everything before is human-readable progress. Grab the LAST
+// {...} block, not the first — the first may be a per-generation log line.
+// (This last-block parse is now the family-wide shared implementation.)
+const maybeParseJson = parseTrailingJson;
+
+/**
+ * Sync invocation. Use for short subcommands (`bench verify`, smoke shapes).
+ * Async variant below for long-running `evolve` calls.
+ */
+export function runDarwin(args, opts = {}) {
+  const start = Date.now();
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const wantJson = opts.json !== false;
+  const argv = buildArgv(args, wantJson);
+  const r = spawnSync('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    cwd: opts.cwd,
+    env: { ...process.env, ...(opts.env || {}) },
+    shell: process.platform === 'win32',
+  });
+  const durationMs = Date.now() - start;
+  const stdout = r.stdout || '';
+  const stderr = r.stderr || '';
+  const classified = classifyDegraded(stderr, r.status, REASON_PREFIX);
+  if (classified.degraded) {
+    return {
+      stdout, stderr,
+      exitCode: r.status ?? 127,
+      json: null,
+      durationMs,
+      degraded: true,
+      reason: classified.reason,
+    };
+  }
+  return {
+    stdout, stderr,
+    exitCode: r.status ?? 0,
+    json: wantJson ? maybeParseJson(stdout) : null,
+    durationMs,
+    degraded: false,
+  };
+}
+
+/**
+ * Async invocation with streaming. Required for `evolve` because the run
+ * can take 10+ minutes and the caller wants progress visibility.
+ *
+ * If `opts.onProgress(line)` is provided, called once per stderr line.
+ * darwin writes per-generation progress to stderr, structured result to
+ * stdout. Cancellable via opts.signal (AbortSignal).
+ */
+export function runDarwinAsync(args, opts = {}) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const wantJson = opts.json !== false;
+    const argv = buildArgv(args, wantJson);
+    const p = spawn('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: opts.cwd,
+      env: { ...process.env, ...(opts.env || {}) },
+      shell: process.platform === 'win32',
+    });
+    let stdout = '', stderr = '', stderrBuf = '';
+    p.stdout?.on('data', (d) => { stdout += d.toString(); });
+    p.stderr?.on('data', (d) => {
+      const s = d.toString();
+      stderr += s;
+      if (opts.onProgress) {
+        stderrBuf += s;
+        const lines = stderrBuf.split('\n');
+        stderrBuf = lines.pop() ?? '';
+        for (const line of lines) opts.onProgress(line);
+      }
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { p.kill('SIGTERM'); } catch { /* ignore */ }
+    }, timeoutMs);
+    if (opts.signal) {
+      opts.signal.addEventListener('abort', () => {
+        try { p.kill('SIGTERM'); } catch { /* ignore */ }
+      }, { once: true });
+    }
+    p.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({
+        stdout,
+        stderr: stderr + String(e?.message ?? e),
+        exitCode: 127, json: null, durationMs: Date.now() - start,
+        degraded: true, reason: `${REASON_PREFIX}-not-available`,
+      });
+    });
+    p.on('close', (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - start;
+      const classified = classifyDegraded(stderr, timedOut ? null : code, REASON_PREFIX);
+      if (classified.degraded) {
+        resolve({
+          stdout, stderr,
+          exitCode: code ?? 127, json: null, durationMs,
+          degraded: true, reason: classified.reason,
+        });
+        return;
+      }
+      resolve({
+        stdout, stderr,
+        exitCode: code ?? 0,
+        json: wantJson ? maybeParseJson(stdout) : null,
+        durationMs,
+        degraded: false,
+      });
+    });
+  });
+}
+
+/**
+ * Match the existing `emitDegradedJsonAndExit` shape used by the
+ * metaharness-umbrella scripts so MCP tool consumers see one contract.
+ * Exit 0 — ADR-150 architectural constraint: ruflo continues to function
+ * when MetaHarness is absent. Same posture as the umbrella scripts.
+ */
+export const emitDarwinDegradedJsonAndExit = makeDegradedEmitter(DARWIN_PKG, DARWIN_PIN_VERSION);
+
+export const DARWIN_VERSION_PIN = DARWIN_PIN;
+
+/**
+ * Resolver for the darwin GEPA LIBRARY entry (`@metaharness/darwin/gepa`).
+ * Lives here (not in gepa.mjs) because gepa.mjs is a CLI script that runs
+ * main() on import — this module is the import-safe home for the darwin
+ * pin. Used by gepa.mjs (genome/validate/render/analyze ops) and by
+ * evolve.mjs --diagnose (failure-class analysis of run transcripts).
+ * Returns the module namespace or null. Never throws on absence.
+ */
+export function importGepa() {
+  return importOptionalLibrary({
+    specifier: '@metaharness/darwin/gepa',
+    pkg: DARWIN_PKG,
+    pinVersion: DARWIN_PIN_VERSION,
+    entryRelPath: 'dist/gepa/index.js',
+  });
+}