@claude-flow/cli 3.32.2 → 3.32.3

package/.claude/helpers/helpers.manifest.json

@@ -1,13 +1,13 @@
 {
   "manifest": {
-    "version": "3.32.2",
+    "version": "3.32.3",
     "files": {
       "auto-memory-hook.mjs": "e3e1033b24704992ddef6b31c7fa9dd7fcd9e1af7935dd77ef73402b916b31e6",
       "hook-handler.cjs": "f87ec28684bfc5fd0a54c46bd2a53a3fb037defe71d0ea4b8a5cb88a2cd87a3f",
       "intelligence.cjs": "5a55d979cb7ba5c8c4f27f3b2e6d686fbb1045d180023b803da672a37e05b915",
-      "statusline.cjs": "f6fcaedad7b521248ba57c494eb1a0ce696679fa3f8709f81edf3fdecef369c2"
+      "statusline.cjs": "af2703bdd710fb52af3221669266771ba1684157f34d77de21373890b5c2a126"
     }
   },
-  "signature": "r7TaWKVLZ6gxssGRM31J6usZrRm1Y5TAZXNmOfeLn+7VzWMrH6pZZPGTfSv6WMW49j8Ko3aamDBtahasWybSAw==",
+  "signature": "D2Utlq4bUJe8VgqtibmGrASrFEyzPh5/MQLn2peimcmNuQT8qHN6uMfmgosF1Q9TCi3G4TkZ2iKMYbZ5U/iaAQ==",
   "algorithm": "ed25519"
 }

package/.claude/helpers/statusline.cjs

@@ -26,11 +26,11 @@ const { execSync } = require('child_process');
 const os = require('os');
 
 // Configuration
-const CONFIG = {
-  maxAgents: 15,
-  // Header identity defaults to project/repository name. Set `author` to
-  // retain the previous `git config user.name` display (#2682).
-  identityMode: (process.env.RUFLO_STATUSLINE_IDENTITY || 'project').toLowerCase(),
+const CONFIG = {
+  maxAgents: 15,
+  // Header identity defaults to project/repository name. Set `author` to
+  // retain the previous `git config user.name` display (#2682).
+  identityMode: (process.env.RUFLO_STATUSLINE_IDENTITY || 'project').toLowerCase(),
   // Session-cost display. Claude Code's cost.total_cost_usd is a client-side
   // estimate that "may differ from your actual bill" and reads as misleading on
   // subscription plans, where token usage is not billed per dollar. These let
@@ -213,9 +213,9 @@ function getStatuslineData() {
   // 60s TTL (#2337 — don't re-spawn the CLI on every rapid re-render) AND the
   // tighter promo-rotation clock (this fix — don't let a still-fresh 60s
   // cache silently freeze the promo/insight row across multiple 20s slots).
-  if (cache.fresh && cache.promoFresh) {
-    return applyLocalOverlays(overlayMemoPromo(cache.data));
-  }
+  if (cache.fresh && cache.promoFresh) {
+    return applyLocalOverlays(overlayMemoPromo(cache.data));
+  }
 
   // #2337: prefer an already-installed CLI bin via direct `node` invocation —
   // no npx, no registry round-trip, no @latest re-resolve per render. Try
@@ -422,7 +422,7 @@ function buildLocalFallback() {
   return applyLocalOverlays({
     user: { name: 'user', gitBranch: '', modelName: 'Claude Code' },
     v3Progress: { domainsCompleted: 0, totalDomains: 5, dddProgress: 0, patternsLearned: 0, sessionsCompleted: 0 },
-    security: { status: 'NONE', findings: 0, cvesFixed: 0, totalCves: 0 },
+    security: { status: 'NONE', findings: 0, cvesFixed: 0, totalCves: 0 },
     swarm: { activeAgents: 0, maxAgents: CONFIG.maxAgents, coordinationActive: false },
     system: { memoryMB: memMB, contextPct: 0, intelligencePct: 0, subAgents: 0 },
     lastUpdated: new Date().toISOString(),
@@ -479,16 +479,16 @@ function readJSON(filePath) {
 
 // ─── Git info (pure-Node / single exec — needed for branch display) ──────────
 
-function getGitInfo() {
-  const result = {
-    name: path.basename(CWD) || 'project', gitBranch: '', modified: 0, untracked: 0,
-    staged: 0, ahead: 0, behind: 0,
-  };
-
-  const script = [
-    'git rev-parse --show-toplevel 2>/dev/null || pwd',
-    'echo "---SEP---"',
-    'git config user.name 2>/dev/null || echo user',
+function getGitInfo() {
+  const result = {
+    name: path.basename(CWD) || 'project', gitBranch: '', modified: 0, untracked: 0,
+    staged: 0, ahead: 0, behind: 0,
+  };
+
+  const script = [
+    'git rev-parse --show-toplevel 2>/dev/null || pwd',
+    'echo "---SEP---"',
+    'git config user.name 2>/dev/null || echo user',
     'echo "---SEP---"',
     'git branch --show-current 2>/dev/null',
     'echo "---SEP---"',
@@ -501,14 +501,14 @@ function getGitInfo() {
   if (!raw) return result;
 
   const parts = raw.split('---SEP---').map(function(s) { return s.trim(); });
-  if (parts.length >= 5) {
-    const projectName = path.basename(parts[0] || CWD) || path.basename(CWD) || 'project';
-    const authorName = parts[1] || 'user';
-    result.name = CONFIG.identityMode === 'author' ? authorName : projectName;
-    result.gitBranch = parts[2] || '';
-
-    if (parts[3]) {
-      for (const line of parts[3].split('\n')) {
+  if (parts.length >= 5) {
+    const projectName = path.basename(parts[0] || CWD) || path.basename(CWD) || 'project';
+    const authorName = parts[1] || 'user';
+    result.name = CONFIG.identityMode === 'author' ? authorName : projectName;
+    result.gitBranch = parts[2] || '';
+
+    if (parts[3]) {
+      for (const line of parts[3].split('\n')) {
         if (!line || line.length < 2) continue;
         const x = line[0], y = line[1];
         if (x === '?' && y === '?') { result.untracked++; continue; }
@@ -517,7 +517,7 @@ function getGitInfo() {
       }
     }
 
-    const ab = (parts[4] || '0 0').split(/\s+/);
+    const ab = (parts[4] || '0 0').split(/\s+/);
     result.ahead = parseInt(ab[0]) || 0;
     result.behind = parseInt(ab[1]) || 0;
   }
@@ -731,7 +731,7 @@ function generateStatusline() {
   const intelligencePct = system.intelligencePct || 0;
   const memoryMB = system.memoryMB || 0;
   const subAgents = system.subAgents || 0;
-  const findings = Math.max(0, security.findings || 0);
+  const findings = Math.max(0, security.findings || 0);
   const secStatus = security.status || 'NONE';
   const adrCount = adrs.count || 0;
   const adrImpl = adrs.implemented || 0;
@@ -786,7 +786,7 @@ function generateStatusline() {
   const hooksColor = hooksEnabled > 0 ? c.brightGreen : c.dim;
   const intellColor = intelligencePct >= 80 ? c.brightGreen : intelligencePct >= 40 ? c.brightYellow : c.dim;
   const swarmInd = coordinationActive ? c.brightGreen + '◉' + c.reset + ' ' : c.dim + '○' + c.reset + ' ';
-  const healthAllGreen = (secStatus === 'CLEAN' || secStatus === 'NONE') && findings === 0;
+  const healthAllGreen = (secStatus === 'CLEAN' || secStatus === 'NONE') && findings === 0;
   const opsParts = [];
   opsParts.push(c.cyan + 'Swarm ' + swarmInd + agentsColor + activeAgents + c.reset + '/' + c.brightWhite + maxAgents + c.reset);
   if (subAgents > 0) opsParts.push(c.brightPurple + '👥 ' + subAgents + c.reset);
@@ -797,14 +797,14 @@ function generateStatusline() {
   if (healthAllGreen) {
     opsParts.push(c.brightGreen + '🛡 ✓' + c.reset);
   } else {
-    if (secStatus === 'PENDING') opsParts.push(c.brightYellow + '🛡 scan pending' + c.reset);
-    else if (secStatus === 'IN_PROGRESS') opsParts.push(c.brightYellow + '🛡 scanning…' + c.reset);
-    else if (secStatus === 'ISSUES') opsParts.push(c.brightRed + '🛡 findings' + c.reset);
-    else if (secStatus === 'STALE') opsParts.push(c.brightYellow + '🛡 scan stale' + c.reset);
-    else if (secStatus !== 'NONE' && secStatus !== 'CLEAN') opsParts.push(c.brightRed + '🛡 ' + secStatus.toLowerCase() + c.reset);
-    if (findings > 0) {
-      opsParts.push(c.brightRed + '⚠ ' + findings + ' finding' + (findings === 1 ? '' : 's') + c.reset);
-    }
+    if (secStatus === 'PENDING') opsParts.push(c.brightYellow + '🛡 scan pending' + c.reset);
+    else if (secStatus === 'IN_PROGRESS') opsParts.push(c.brightYellow + '🛡 scanning…' + c.reset);
+    else if (secStatus === 'ISSUES') opsParts.push(c.brightRed + '🛡 findings' + c.reset);
+    else if (secStatus === 'STALE') opsParts.push(c.brightYellow + '🛡 scan stale' + c.reset);
+    else if (secStatus !== 'NONE' && secStatus !== 'CLEAN') opsParts.push(c.brightRed + '🛡 ' + secStatus.toLowerCase() + c.reset);
+    if (findings > 0) {
+      opsParts.push(c.brightRed + '⚠ ' + findings + ' finding' + (findings === 1 ? '' : 's') + c.reset);
+    }
   }
   lines.push(opsParts.join('  ' + c.dim + '·' + c.reset + '  '));
 

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 1,
-  "generatedAt": "2026-07-17T04:00:15.717Z",
-  "gitSha": "61047df4",
+  "generatedAt": "2026-07-17T19:02:35.545Z",
+  "gitSha": "099b8df1",
   "catalog": {
     "agents": 164,
     "tools": 387,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.32.2",
+  "version": "3.32.3",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -111,7 +111,7 @@
     "yaml": "^2.8.0"
   },
   "optionalDependencies": {
-    "@claude-flow/memory": "^3.0.0-alpha.21",
+    "@claude-flow/memory": "^3.0.0-alpha.21",
     "@claude-flow/security": "^3.0.0-alpha.10",
     "agentdb": "^3.0.0-alpha.17",
     "agentic-flow": "^3.0.0-alpha.1",

package/plugins/ruflo-metaharness/scripts/smoke.sh

@@ -799,8 +799,8 @@ TOOLS=$(grep -oE "name: 'metaharness_[a-z_]+'" "$WRAPPER" 2>/dev/null \
 COUNT=0
 for t in $TOOLS; do
   COUNT=$((COUNT + 1))
-  # audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
-  grep -q "mcp__claude-flow__${t}" "$CMD" 2>/dev/null \
+  # audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
+  grep -q "mcp__claude-flow__${t}" "$CMD" 2>/dev/null \
     || miss="$miss ${t}-not-in-claude-md"
 done
 # Count derived from the wrapper source (mint deliberately excluded — see
@@ -1520,9 +1520,9 @@ grep -q "name: 'metaharness_drift_from_history'" "$WRAPPER" 2>/dev/null || miss=
 grep -q "drift-from-history.mjs" "$WRAPPER" 2>/dev/null || miss="$miss no-script-dispatch"
 grep -q "baselineSince" "$WRAPPER" 2>/dev/null || miss="$miss no-baseline-since-input"
 # CLAUDE.md mentions both surfaces
-CMD="$ROOT/../../CLAUDE.md"
-# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
-grep -q "mcp__claude-flow__metaharness_drift_from_history" "$CMD" 2>/dev/null || miss="$miss claude-md-no-mcp"
+CMD="$ROOT/../../CLAUDE.md"
+# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
+grep -q "mcp__claude-flow__metaharness_drift_from_history" "$CMD" 2>/dev/null || miss="$miss claude-md-no-mcp"
 grep -q "ruflo metaharness drift-from-history" "$CMD" 2>/dev/null || miss="$miss claude-md-no-subcommand"
 # Phase 4 includes the new positive-case assertions
 T="$ROOT/scripts/test-mcp-tools.mjs"
@@ -1806,9 +1806,9 @@ grep -q "audit-trend structural-distance integration" "$F" 2>/dev/null || miss="
 grep -q "Graceful fallback when fingerprint missing" "$F" 2>/dev/null || miss="$miss no-fallback-step"
 grep -q "Distance alert gate exits 1" "$F" 2>/dev/null || miss="$miss no-alert-step"
 # CLAUDE.md documents the new MCP tool + subcommand
-CMD="$ROOT/../../CLAUDE.md"
-# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
-grep -q "mcp__claude-flow__metaharness_similarity" "$CMD" 2>/dev/null || miss="$miss claude-md-no-mcp-tool"
+CMD="$ROOT/../../CLAUDE.md"
+# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
+grep -q "mcp__claude-flow__metaharness_similarity" "$CMD" 2>/dev/null || miss="$miss claude-md-no-mcp-tool"
 grep -q "ruflo metaharness similarity" "$CMD" 2>/dev/null || miss="$miss claude-md-no-subcommand"
 grep -q -- "--alert-on-distance-below" "$CMD" 2>/dev/null || miss="$miss claude-md-no-distance-flag"
 [[ -z "$miss" ]] && ok || bad "$miss"
@@ -2124,9 +2124,9 @@ grep -q "Ruflo remains operational if every MetaHarness package is removed" "$F"
 # All 4 rules documented
 grep -q "no-metaharness-smoke.yml" "$F" || miss="$miss no-ci-gate-ref"
 # Command surface + tool surface enumerated
-grep -q "npx ruflo metaharness score" "$F" || miss="$miss no-cli-example"
-# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
-grep -q "mcp__claude-flow__metaharness_" "$F" || miss="$miss no-mcp-tool-list"
+grep -q "npx ruflo metaharness score" "$F" || miss="$miss no-cli-example"
+# audit-allow: standalone-mcp-prefix — this checks the repository CLAUDE.md, not a plugin skill.
+grep -q "mcp__claude-flow__metaharness_" "$F" || miss="$miss no-mcp-tool-list"
 # Routing + parallel-log integration both mentioned
 grep -q "CLAUDE_FLOW_ROUTER_NEURAL\|CLAUDE_FLOW_ROUTER_PARALLEL_LOG" "$F" || miss="$miss no-routing-flags"
 # 3-criteria gate

package/dist/src/agenticow/speculative-exploration.d.ts

@@ -1,148 +0,0 @@
-/**
- * Speculative branch-and-promote — parallel A/B solution exploration over
- * COW memory branches (agenticow step 4).
- *
- * Concept (from agenticow's examples/ab-branches + promotion-pipeline):
- *   Fan out N candidate approaches, each on its own Copy-On-Write branch of a
- *   shared base `.rvf` memory. Each candidate explores/writes independently
- *   against its own branch handle. Score the results, PROMOTE the winner's
- *   branch back into base, and DISCARD the losers — which for agenticow means
- *   deleting the branch files (162 bytes each), not re-copying GB of state.
- *
- *   This is the memory-state analogue of the git-worktree-per-agent pattern
- *   used for parallel code agents: cheap speculative forks, keep one, throw the
- *   rest away at near-zero cost.
- *
- * This module is intentionally COMPOSED ON TOP of the existing agenticow verbs
- * (`fork` / `promote`) and the shared `_agenticow.ts` helpers — it does not
- * reimplement COW semantics. It is generic over the candidate result type so
- * callers supply their own `fn` (what to do on each branch) and `score`
- * (how good the branch turned out).
- *
- * @module @claude-flow/cli/agenticow/speculative-exploration
- */
-import { type AgenticowApi } from '../mcp-tools/agenticow-loader.js';
-/** A COW memory handle (agenticow `AgenticMemory`), kept `any` to avoid a hard type dep. */
-export type MemoryHandle = any;
-export interface SpeculativeCandidate<TResult> {
-    /** Human-readable branch label (validated: `[A-Za-z0-9_.\-:/@]`). */
-    label: string;
-    /**
-     * The exploration to run against this candidate's isolated branch handle.
-     * Receives the forked branch (read-through of base ∪ its own edits). May
-     * ingest, delete, query, etc. Its return value is fed to `score`.
-     */
-    fn: (branch: MemoryHandle) => TResult | Promise<TResult>;
-}
-export interface ExploreOptions {
-    /**
-     * Maps a candidate label to the on-disk path for its branch `.rvf` file.
-     * Loser paths are deleted after scoring.
-     */
-    branchPath: (label: string) => string;
-    /** Persist winner-branch + save manifests. Default true. */
-    persist?: boolean;
-    /**
-     * Tie-break: when two candidates tie on score, the earlier one (lower index)
-     * wins by default (stable). Set `'last'` to prefer the later candidate.
-     */
-    tieBreak?: 'first' | 'last';
-    /**
-     * PROMOTION GATE (ADR-171). A branch is promote-INELIGIBLE unless cleared by a
-     * real evaluation oracle, or by an explicitly-accepted Fable judge. When
-     * provided, the top-scoring candidate is promoted ONLY if this returns
-     * `{cleared:true, by:'oracle:test-exec'}` or `{cleared:true, by:'judge:fable'}`.
-     * `proxy:structural` can NEVER clear a promote — score rank alone does not
-     * graduate work into base. Omit for legacy score-only promotion (unverified).
-     */
-    clearance?: (winnerResult: unknown, label: string) => Promise<{
-        cleared: boolean;
-        by: PromotionProvenance;
-        reason?: string;
-    }>;
-    /**
-     * Force the clearance gate even without a `clearance` fn — a missing gate then
-     * means the winner is ineligible (fail-closed). Default: gate enforced iff
-     * `clearance` is supplied.
-     */
-    requireClearance?: boolean;
-}
-/** Provenance of a promotion decision (ADR-171 trust tiers). */
-export type PromotionProvenance = 'oracle:test-exec' | 'judge:fable' | 'proxy:structural' | 'unverified';
-/**
- * Causal failure receipt (ADR-171). Emitted for every discarded loser and for
- * an ineligible/failed winner — a rollback that loses *why* is half-useful.
- */
-export interface SpeculativeReceipt {
-    label: string;
-    score: number;
-    /** What the branch changed vs its lineage, when introspectable. */
-    diff: {
-        added: number[];
-        overridden: number[];
-        deleted: number[];
-    } | null;
-    /** Why this branch did not graduate. */
-    outcome: 'discarded-loser' | 'winner-ineligible' | 'winner-failed';
-    provenance: PromotionProvenance;
-    reason?: string;
-}
-export interface SpeculativeBranchOutcome<TResult> {
-    label: string;
-    path: string;
-    score: number;
-    result: TResult;
-    /** true for the promoted winner, false for discarded losers. */
-    kept: boolean;
-}
-export interface SpeculativeResult<TResult> {
-    /** Label of the winning (promoted) candidate. */
-    winner: string;
-    /** label → score for every candidate. */
-    scores: Record<string, number>;
-    /** Whether the winner was successfully promoted into base. */
-    promoted: boolean;
-    /** How the promotion decision was reached (ADR-171 provenance). */
-    promotedBy: PromotionProvenance;
-    /** Human-readable promotion decision, e.g. 'promoted:oracle:test-exec' or 'ineligible:proxy-cannot-clear'. */
-    promotionDecision: string;
-    /** agenticow promote() stats for the winner ({ ingested, deleted }). */
-    promoteStats: {
-        ingested: number;
-        deleted: number;
-    } | null;
-    /** Labels of the discarded losers whose branch files were deleted. */
-    discarded: string[];
-    /** Causal failure receipts for discarded losers + an ineligible winner. */
-    receipts: SpeculativeReceipt[];
-    /** Per-candidate detail (score, path, result, kept). */
-    branches: SpeculativeBranchOutcome<TResult>[];
-}
-/**
- * Fork one branch per candidate off `base`, run each `fn` against its own
- * branch handle, score the results, PROMOTE the best branch back into `base`,
- * and DISCARD (delete the files of) the rest.
- *
- * The caller owns `base`: this function mutates it in-memory via `promote()`
- * but does NOT save it (only the caller knows the base file path). Persist the
- * base yourself after this resolves (e.g. `base.save(manifestFor(basePath))`).
- *
- * @param base       An opened agenticow memory handle to branch from.
- * @param candidates The A/B candidates — each `{label, fn}`.
- * @param score      Scores a candidate's result; higher wins.
- * @param opts       Branch-path mapping + persistence knobs.
- */
-export declare function explore<TResult>(base: MemoryHandle, candidates: SpeculativeCandidate<TResult>[], score: (result: TResult, label: string) => number, opts: ExploreOptions): Promise<SpeculativeResult<TResult>>;
-/**
- * Convenience wrapper that owns the whole lifecycle for a file-path base:
- * loads agenticow (returns `null` when the optional dep is absent), opens the
- * base with its lineage, runs {@link explore}, then persists the mutated base.
- *
- * Returns `null` when agenticow is not installed so callers can emit the
- * standard `{degraded:true}` contract.
- */
-export declare function exploreFromPath<TResult>(basePath: string, candidates: SpeculativeCandidate<TResult>[], score: (result: TResult, label: string) => number, opts: ExploreOptions & {
-    dimension?: number;
-    api?: AgenticowApi;
-}): Promise<SpeculativeResult<TResult> | null>;
-//# sourceMappingURL=speculative-exploration.d.ts.map

package/dist/src/agenticow/speculative-exploration.js

@@ -1,218 +0,0 @@
-/**
- * Speculative branch-and-promote — parallel A/B solution exploration over
- * COW memory branches (agenticow step 4).
- *
- * Concept (from agenticow's examples/ab-branches + promotion-pipeline):
- *   Fan out N candidate approaches, each on its own Copy-On-Write branch of a
- *   shared base `.rvf` memory. Each candidate explores/writes independently
- *   against its own branch handle. Score the results, PROMOTE the winner's
- *   branch back into base, and DISCARD the losers — which for agenticow means
- *   deleting the branch files (162 bytes each), not re-copying GB of state.
- *
- *   This is the memory-state analogue of the git-worktree-per-agent pattern
- *   used for parallel code agents: cheap speculative forks, keep one, throw the
- *   rest away at near-zero cost.
- *
- * This module is intentionally COMPOSED ON TOP of the existing agenticow verbs
- * (`fork` / `promote`) and the shared `_agenticow.ts` helpers — it does not
- * reimplement COW semantics. It is generic over the candidate result type so
- * callers supply their own `fn` (what to do on each branch) and `score`
- * (how good the branch turned out).
- *
- * @module @claude-flow/cli/agenticow/speculative-exploration
- */
-import { existsSync, rmSync } from 'node:fs';
-import { loadAgenticow, openWithLineage, manifestFor, resolveMemoryPath, validateLabel, } from '../mcp-tools/agenticow-loader.js';
-function safeDiff(branch) {
-    try {
-        const d = branch.diff?.();
-        return d ? { added: d.added ?? [], overridden: d.overridden ?? [], deleted: d.deleted ?? [] } : null;
-    }
-    catch {
-        return null;
-    }
-}
-function deleteBranchFiles(path) {
-    for (const p of [path, manifestFor(path)]) {
-        try {
-            if (existsSync(p))
-                rmSync(p, { recursive: true, force: true });
-        }
-        catch {
-            /* best-effort discard; a leftover 162-byte file is not fatal */
-        }
-    }
-}
-/**
- * Fork one branch per candidate off `base`, run each `fn` against its own
- * branch handle, score the results, PROMOTE the best branch back into `base`,
- * and DISCARD (delete the files of) the rest.
- *
- * The caller owns `base`: this function mutates it in-memory via `promote()`
- * but does NOT save it (only the caller knows the base file path). Persist the
- * base yourself after this resolves (e.g. `base.save(manifestFor(basePath))`).
- *
- * @param base       An opened agenticow memory handle to branch from.
- * @param candidates The A/B candidates — each `{label, fn}`.
- * @param score      Scores a candidate's result; higher wins.
- * @param opts       Branch-path mapping + persistence knobs.
- */
-export async function explore(base, candidates, score, opts) {
-    if (!base)
-        throw new Error('base memory handle is required');
-    if (!Array.isArray(candidates) || candidates.length === 0) {
-        throw new Error('at least one candidate is required');
-    }
-    if (typeof score !== 'function')
-        throw new Error('score function is required');
-    if (!opts || typeof opts.branchPath !== 'function') {
-        throw new Error('opts.branchPath(label) is required');
-    }
-    const persist = opts.persist !== false;
-    const tieBreak = opts.tieBreak ?? 'first';
-    // Reject duplicate labels up front — two branches to the same file would clash.
-    const seen = new Set();
-    const live = [];
-    // 1) Fork + explore each candidate on its own isolated branch.
-    for (const c of candidates) {
-        const label = validateLabel(c.label);
-        if (seen.has(label))
-            throw new Error(`duplicate candidate label: ${label}`);
-        seen.add(label);
-        if (typeof c.fn !== 'function')
-            throw new Error(`candidate ${label} is missing fn()`);
-        const path = resolveMemoryPath(opts.branchPath(label));
-        const branch = base.fork(label, path);
-        const result = await c.fn(branch);
-        const s = Number(score(result, label));
-        live.push({ label, path, branch, result, score: Number.isFinite(s) ? s : -Infinity });
-    }
-    // 2) Pick the winner (highest score; stable tie-break).
-    let winnerIdx = 0;
-    for (let i = 1; i < live.length; i++) {
-        const better = tieBreak === 'last'
-            ? live[i].score >= live[winnerIdx].score
-            : live[i].score > live[winnerIdx].score;
-        if (better)
-            winnerIdx = i;
-    }
-    const scores = {};
-    for (const l of live)
-        scores[l.label] = l.score;
-    const winner = live[winnerIdx];
-    const receipts = [];
-    // 3) PROMOTION GATE (ADR-171). The top score is a *nominee*, not a promotion.
-    //    A branch graduates into base only when cleared by a real oracle or an
-    //    explicitly-accepted Fable judge. proxy:structural / score-only never
-    //    clears. Fail-closed: requireClearance with no gate = ineligible.
-    const gate = opts.clearance;
-    const enforce = opts.requireClearance ?? !!gate;
-    let promoted = false;
-    let promotedBy = 'unverified';
-    let promotionDecision;
-    let promoteStats = null;
-    let clearance;
-    if (gate) {
-        try {
-            clearance = await gate(winner.result, winner.label);
-        }
-        catch (e) {
-            clearance = { cleared: false, by: 'proxy:structural', reason: `clearance threw: ${e?.message ?? e}` };
-        }
-    }
-    else if (enforce) {
-        clearance = { cleared: false, by: 'proxy:structural', reason: 'requireClearance set but no clearance gate provided' };
-    }
-    else {
-        clearance = { cleared: true, by: 'unverified', reason: 'legacy score-only promotion (no gate configured)' };
-    }
-    // proxy:structural can NEVER clear a promote, regardless of `cleared`.
-    const cleared = clearance.cleared
-        && (clearance.by === 'oracle:test-exec' || clearance.by === 'judge:fable' || (!enforce && clearance.by === 'unverified'));
-    if (cleared) {
-        promoteStats = winner.branch.promote(base);
-        if (persist)
-            winner.branch.save?.(manifestFor(winner.path));
-        winner.branch.close?.();
-        promoted = true;
-        promotedBy = clearance.by;
-        promotionDecision = `promoted:${clearance.by}`;
-    }
-    else {
-        // Winner is ineligible — base stays UNCHANGED. Emit a causal receipt and
-        // discard the branch (it did not earn graduation).
-        promotedBy = clearance.by;
-        promotionDecision = `ineligible:${clearance.by === 'proxy:structural' ? 'proxy-cannot-clear' : clearance.by}`;
-        receipts.push({
-            label: winner.label,
-            score: winner.score,
-            diff: safeDiff(winner.branch),
-            outcome: 'winner-ineligible',
-            provenance: clearance.by,
-            reason: clearance.reason ?? 'not cleared by oracle or accepted Fable judge',
-        });
-        winner.branch.close?.();
-        deleteBranchFiles(winner.path);
-    }
-    // 4) Discard the losers — receipt each, close handle, delete files.
-    const discarded = [];
-    for (let i = 0; i < live.length; i++) {
-        if (i === winnerIdx)
-            continue;
-        receipts.push({
-            label: live[i].label,
-            score: live[i].score,
-            diff: safeDiff(live[i].branch),
-            outcome: 'discarded-loser',
-            provenance: 'proxy:structural',
-            reason: `lower score than winner (${live[i].score} < ${winner.score})`,
-        });
-        live[i].branch.close?.();
-        deleteBranchFiles(live[i].path);
-        discarded.push(live[i].label);
-    }
-    const branches = live.map((l, i) => ({
-        label: l.label,
-        path: l.path,
-        score: l.score,
-        result: l.result,
-        kept: i === winnerIdx && promoted,
-    }));
-    return {
-        winner: winner.label,
-        scores,
-        promoted,
-        promotedBy,
-        promotionDecision,
-        promoteStats,
-        discarded,
-        receipts,
-        branches,
-    };
-}
-/**
- * Convenience wrapper that owns the whole lifecycle for a file-path base:
- * loads agenticow (returns `null` when the optional dep is absent), opens the
- * base with its lineage, runs {@link explore}, then persists the mutated base.
- *
- * Returns `null` when agenticow is not installed so callers can emit the
- * standard `{degraded:true}` contract.
- */
-export async function exploreFromPath(basePath, candidates, score, opts) {
-    const api = opts.api ?? (await loadAgenticow());
-    if (!api)
-        return null;
-    const resolvedBase = resolveMemoryPath(basePath);
-    const base = await openWithLineage(api, resolvedBase, opts.dimension);
-    try {
-        const result = await explore(base, candidates, score, opts);
-        if (opts.persist !== false) {
-            base.save?.(manifestFor(resolvedBase));
-        }
-        return result;
-    }
-    finally {
-        base.close?.();
-    }
-}
-//# sourceMappingURL=speculative-exploration.js.map