claude-flow 3.20.0 → 3.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/agenticow/speculative-exploration.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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/v3/@claude-flow/cli/dist/src/agenticow/speculative-exploration.js

@@ -0,0 +1,218 @@
+/**
+ * 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

package/v3/@claude-flow/cli/dist/src/commands/autopilot.js

@@ -6,6 +6,45 @@
  */
 import { output } from '../output.js';
 import { loadState, saveState, appendLog, loadLog, discoverTasks, getProgress, calculateReward, tryLoadLearning, validateNumber, validateTaskSources, LOG_FILE, } from '../autopilot-state.js';
+import { getCheckpointGate, CheckpointGate } from '../services/checkpoint-gate.js';
+/**
+ * Opt-in checkpoint/rollback gate for the autopilot tick (agenticow step 3).
+ *
+ * The autopilot loop's memory mutation happens OUT OF PROCESS — a re-engaged
+ * tick returns a continuation prompt, and the spawned agent (plus agentic-flow
+ * learning) mutates `.rvf` memory. So there is no in-process fn to wrap with
+ * CheckpointGate.guard() here; instead we bracket the loop across ticks:
+ *   - checkpoint the configured `.rvf` right before handing off a risky tick
+ *     (re-engage), and
+ *   - roll it back when the loop's own regression signal fires (stall auto-disable).
+ *
+ * Entirely opt-in: it does nothing unless CLAUDE_FLOW_AUTOPILOT_CHECKPOINT_MEM
+ * points at an `.rvf` file the loop mutates, agenticow is installed, and the
+ * CLAUDE_FLOW_AGENTICOW_DISABLE kill switch is unset. Every call is non-fatal —
+ * a checkpoint/rollback failure never breaks the loop.
+ */
+async function checkpointTick(label) {
+    const memPath = CheckpointGate.configuredMemPath();
+    if (!memPath)
+        return;
+    try {
+        const r = await getCheckpointGate().checkpoint(memPath, label);
+        if (r.ok)
+            appendLog({ ts: Date.now(), event: 'checkpoint', label, memPath });
+    }
+    catch { /* non-fatal: memory branching is best-effort */ }
+}
+async function rollbackTick(reason) {
+    const memPath = CheckpointGate.configuredMemPath();
+    if (!memPath)
+        return;
+    try {
+        const r = await getCheckpointGate().rollback(memPath);
+        if (r.ok)
+            appendLog({ ts: Date.now(), event: 'rollback', reason, memPath });
+    }
+    catch { /* non-fatal */ }
+}
 // ── Check Handler (for Stop hook) ─────────────────────────────
 export async function autopilotCheck() {
     const state = loadState();
@@ -47,6 +86,9 @@ export async function autopilotCheck() {
         state.enabled = false;
         saveState(state);
         appendLog({ ts: Date.now(), event: 'stall-auto-disable', iterations: state.iterations, completed: progress.completed });
+        // Regression signal: the loop stalled. Roll `.rvf` memory back to the last
+        // good per-tick checkpoint (opt-in via CLAUDE_FLOW_AUTOPILOT_CHECKPOINT_MEM).
+        await rollbackTick('stall-auto-disable');
         return { allowStop: true, reason: `Stalled: no progress in 10 iterations (${progress.completed}/${progress.total} complete)` };
     }
     // Re-engage
@@ -54,6 +96,9 @@ export async function autopilotCheck() {
     state.lastCheck = Date.now();
     state.history.push({ ts: Date.now(), iteration: state.iterations, completed: progress.completed, total: progress.total });
     saveState(state);
+    // Checkpoint `.rvf` memory before the risky tick runs (opt-in). The next
+    // check() rolls back to here if this tick regresses (stall detection above).
+    await checkpointTick(`autopilot-iter-${state.iterations}`);
     const stallWarning = isStalled
         ? '\nWARNING: No progress in 5 iterations. Consider breaking tasks into smaller subtasks or trying a different approach.'
         : '';

package/v3/@claude-flow/cli/dist/src/commands/doctor.js

@@ -13,6 +13,7 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
 import { isEncryptedBlob } from '../encryption/vault.js';
+import { resolveMemoryPackageFromProject, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
 // Promisified exec with proper shell and env inheritance for cross-platform support
 const execAsync = promisify(exec);
 /**
@@ -244,6 +245,37 @@ async function checkMemoryDatabase() {
     }
     return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
 }
+// #2545: Check that the self-learning bridge can actually load @claude-flow/memory
+// the SAME way the SessionStart auto-memory hook does. On the documented `npx ruflo`
+// path the package lands in the npx cache — unreachable from the project — so the
+// hook silently no-op'd with no signal anywhere. This surfaces it.
+async function checkLearningBridge() {
+    const cwd = process.cwd();
+    const hookPath = join(cwd, '.claude', 'helpers', 'auto-memory-hook.mjs');
+    // Only relevant once init has deployed the hook; otherwise stay quiet.
+    if (!existsSync(hookPath)) {
+        return {
+            name: 'Learning Bridge',
+            status: 'pass',
+            message: 'auto-memory hook not installed (run: npx ruflo@latest init)',
+        };
+    }
+    const distPath = resolveMemoryPackageFromProject(cwd);
+    if (distPath) {
+        const version = readMemoryPackageVersion(distPath);
+        return {
+            name: 'Learning Bridge',
+            status: 'pass',
+            message: `@claude-flow/memory resolvable${version ? ` (v${version})` : ''}`,
+        };
+    }
+    return {
+        name: 'Learning Bridge',
+        status: 'fail',
+        message: '@claude-flow/memory NOT resolvable — SessionStart self-learning imports are a silent no-op',
+        fix: 'npx ruflo@latest doctor --fix   (records resolver sidecar) — or: npm i -D @claude-flow/memory',
+    };
+}
 // Check API keys
 async function checkApiKeys() {
     const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];
@@ -1036,6 +1068,7 @@ export const doctorCommand = {
             checkStaleSettingsNpx, // #2448 — runaway `npx @latest` in statusLine/hooks
             checkDaemonStatus,
             checkMemoryDatabase,
+            checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
             checkApiKeys,
             checkMcpServers,
             checkAIDefence, // #1807
@@ -1057,6 +1090,8 @@ export const doctorCommand = {
             'stale-settings': checkStaleSettingsNpx, // #2448
             'daemon': checkDaemonStatus,
             'memory': checkMemoryDatabase,
+            'learning': checkLearningBridge, // #2545
+            'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,
             'git': checkGit,
             'mcp': checkMcpServers,
@@ -1107,6 +1142,27 @@ export const doctorCommand = {
             spinner.stop();
             output.writeln(output.error('Failed to run health checks'));
         }
+        // #2545: --fix / --install can actually repair the Learning Bridge by
+        // recording the resolver sidecar. When doctor runs via `npx ruflo`, the CLI
+        // CAN resolve its optional @claude-flow/memory dep (it is in the same npx
+        // cache), so writing the sidecar makes the SessionStart hook find it.
+        if ((showFix || autoInstall)) {
+            const lbResult = results.find(r => r.name === 'Learning Bridge');
+            if (lbResult && lbResult.status === 'fail') {
+                const record = recordMemoryPackagePath(process.cwd(), 'doctor');
+                if (record) {
+                    const newCheck = await checkLearningBridge();
+                    const idx = results.findIndex(r => r.name === 'Learning Bridge');
+                    if (idx !== -1)
+                        results[idx] = newCheck;
+                    const fixIdx = fixes.findIndex(f => f.startsWith('Learning Bridge:'));
+                    if (fixIdx !== -1 && newCheck.status === 'pass')
+                        fixes.splice(fixIdx, 1);
+                    output.writeln(output.success(`Repaired Learning Bridge — wrote .claude-flow/memory-package.json → ${record.distPath}`));
+                    output.writeln(formatCheck(newCheck));
+                }
+            }
+        }
         // Auto-install missing dependencies if requested
         if (autoInstall) {
             const claudeCodeResult = results.find(r => r.name === 'Claude Code CLI');