Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix: #2250 model router escalation override + #2251 daemon trigger headless race (3.10.31)

ruv28eb57543be9
diff --git a/package.json b/package.json
index 5f683fb94a..72c8cd0d15 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.10.30",
+ "version": "3.10.31",
"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",
diff --git a/ruflo/package.json b/ruflo/package.json
index e9bae1a932..2e08cc5589 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.10.30",
+ "version": "3.10.31",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
diff --git a/v3/@claude-flow/cli/__tests__/issue-2250-2251-regression.test.ts b/v3/@claude-flow/cli/__tests__/issue-2250-2251-regression.test.ts
new file mode 100644
index 0000000000..e5634fd63f
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-2250-2251-regression.test.ts
@@ -0,0 +1,141 @@
+/**
+ * CI regression guards for #2250 + #2251.
+ *
+ * #2250 — model-router.selectModel() used to escalate `sonnet → opus` and
+ * `haiku → sonnet` on ~every trivial route because the `uncertainty` formula
+ * is structurally large (~0.6-0.7) and the gate fires at 0.15. The fix:
+ * skip escalation when the bandit has confidently learned the escalation
+ * target is meaningfully worse than the selected model. This test loads
+ * the EXACT suppressed-opus prior from the bug report (Beta(3.8, 17.2),
+ * mean ≈ 0.18) into the low-complexity bucket and asserts (a) opus is
+ * selected on <20% of trivial routes (was ~40% before the fix), and
+ * (b) haiku appears as a final pick (was 0/N before the fix).
+ *
+ * #2251 — WorkerDaemon constructor kicked off `initHeadlessExecutor()`
+ * fire-and-forget, so `daemon.triggerWorker()` called immediately after
+ * construction would see `headlessAvailable = false` and fall through to
+ * the local stub in ~2ms. The fix: store the init promise and await it
+ * inside triggerWorker(). This test confirms triggerWorker() does not
+ * resolve before initHeadlessExecutor() settles.
+ */
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ModelRouter } from '../src/ruvector/model-router.js';
+import { WorkerDaemon } from '../src/services/worker-daemon.js';
+
+let cwdRestore: string;
+let tmpDir: string;
+
+beforeEach(() => {
+ cwdRestore = process.cwd();
+ tmpDir = mkdtempSync(join(tmpdir(), 'issue-2250-2251-'));
+ process.chdir(tmpDir);
+});
+
+afterEach(() => {
+ process.chdir(cwdRestore);
+ rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('#2250 — escalation does not override learned opus suppression', () => {
+ it('routes trivial tasks to haiku/sonnet at least 80% with suppressed-opus prior', async () => {
+ // Seed `.swarm/model-router-state.json` with the prior from the bug report
+ // (opus mean ≈ 0.18, sonnet ≈ 0.64, haiku ≈ 0.60 in the low bucket).
+ mkdirSync(join(tmpDir, '.swarm'), { recursive: true });
+ const state = {
+ priors: {
+ low: {
+ haiku: { alpha: 3.0, beta: 2.0 },
+ sonnet: { alpha: 12.2, beta: 6.8 },
+ opus: { alpha: 3.8, beta: 17.2 },
+ inherit: { alpha: 1, beta: 1 },
+ },
+ med: { haiku: { alpha: 1, beta: 1 }, sonnet: { alpha: 1, beta: 1 }, opus: { alpha: 1, beta: 1 }, inherit: { alpha: 1, beta: 1 } },
+ high: { haiku: { alpha: 1, beta: 1 }, sonnet: { alpha: 1, beta: 1 }, opus: { alpha: 1, beta: 1 }, inherit: { alpha: 1, beta: 1 } },
+ },
+ };
+ writeFileSync(join(tmpDir, '.swarm/model-router-state.json'), JSON.stringify(state));
+
+ const router = new ModelRouter();
+ const N = 50;
+ const counts: Record<string, number> = { haiku: 0, sonnet: 0, opus: 0 };
+ for (let i = 0; i < N; i++) {
+ // Trivial low-complexity task (matches bug report's example).
+ const r = await router.route(`Add a single option to a select dropdown ${i}`);
+ counts[r.model] = (counts[r.model] ?? 0) + 1;
+ }
+
+ const opusRate = counts.opus / N;
+ expect(opusRate).toBeLessThan(0.20); // before fix: ~0.40
+ expect(counts.haiku + counts.sonnet).toBeGreaterThanOrEqual(N - counts.opus);
+ expect(counts.haiku).toBeGreaterThan(0); // before fix: 0/N
+ }, 30_000);
+
+ it('still escalates on cold-start (Beta(1,1) priors)', async () => {
+ // No state file → uniform priors → escalation guard should NOT trigger
+ // (target mean ≈ selected mean), so the prior router behavior is preserved
+ // for unlearned routers. We just assert the route succeeds without crashing
+ // and returns one of the three valid models.
+ const router = new ModelRouter();
+ const r = await router.route('Refactor the entire authentication subsystem');
+ expect(['haiku', 'sonnet', 'opus']).toContain(r.model);
+ }, 10_000);
+
+ it('respects CLAUDE_FLOW_MAX_UNCERTAINTY env override', async () => {
+ // With maxUncertainty=0.99 the escalation gate effectively never fires,
+ // so the selected model is always the Thompson-sampled winner unmodified.
+ const old = process.env.CLAUDE_FLOW_MAX_UNCERTAINTY;
+ process.env.CLAUDE_FLOW_MAX_UNCERTAINTY = '0.99';
+ try {
+ // The env is read at module load via `envMaxUncertainty()` in
+ // DEFAULT_CONFIG. Pass it through config explicitly so the test
+ // doesn't depend on module reload order.
+ const router = new ModelRouter({ maxUncertainty: 0.99 });
+ const r = await router.route('simple low-complexity task');
+ expect(['haiku', 'sonnet', 'opus']).toContain(r.model);
+ } finally {
+ if (old === undefined) delete process.env.CLAUDE_FLOW_MAX_UNCERTAINTY;
+ else process.env.CLAUDE_FLOW_MAX_UNCERTAINTY = old;
+ }
+ });
+});
+
+describe('#2251 — daemon.triggerWorker awaits headless init', () => {
+ it('does not resolve triggerWorker before initHeadlessExecutor settles', async () => {
+ const daemon = new WorkerDaemon(tmpDir);
+
+ // Replace the field with a deferred promise we control so we can prove
+ // triggerWorker waits for it before calling executeWorker.
+ let initResolved = false;
+ let resolveInit!: () => void;
+ const gatedInit = new Promise<void>((resolve) => {
+ resolveInit = () => {
+ initResolved = true;
+ resolve();
+ };
+ });
+ // The trigger awaits this exact field per the #2251 fix.
+ (daemon as unknown as { headlessInitPromise: Promise<void> }).headlessInitPromise = gatedInit;
+
+ // Stub executeWorker so we can prove its call order vs init resolution
+ // without actually running a worker.
+ let executeCalledBeforeInit: boolean | null = null;
+ (daemon as unknown as { executeWorker: (...a: unknown[]) => Promise<unknown> }).executeWorker =
+ vi.fn(async () => {
+ executeCalledBeforeInit = !initResolved; // record the order
+ return { workerId: 'x', type: 'map', success: true, durationMs: 1, timestamp: new Date() };
+ });
+
+ const triggerP = daemon.triggerWorker('map');
+ // Yield a tick so any non-awaited path would already have called executeWorker.
+ await new Promise((r) => setImmediate(r));
+ expect(executeCalledBeforeInit).toBeNull(); // executeWorker not called yet — still gated
+
+ resolveInit();
+ await triggerP;
+ expect(executeCalledBeforeInit).toBe(false); // executeWorker called AFTER init
+ });
+});
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 5aaaf30cca..be4c44d35f 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.10.30",
+ "version": "3.10.31",
"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",
diff --git a/v3/@claude-flow/cli/src/ruvector/model-router.ts b/v3/@claude-flow/cli/src/ruvector/model-router.ts
index d2a0c4e8e7..f50b1e6042 100644
--- a/v3/@claude-flow/cli/src/ruvector/model-router.ts
+++ b/v3/@claude-flow/cli/src/ruvector/model-router.ts
@@ -325,9 +325,20 @@ function migratePriors(p: unknown): BucketedPriors {
// Default Configuration
// ============================================================================
+// #2250 — env override for maxUncertainty so callers can suppress the
+// escalation without recompiling. Parsed once at module load; invalid /
+// out-of-range values fall through to the default below.
+function envMaxUncertainty(): number | undefined {
+ const raw = process.env.CLAUDE_FLOW_MAX_UNCERTAINTY;
+ if (!raw) return undefined;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n < 0 || n > 1) return undefined;
+ return n;
+}
+
const DEFAULT_CONFIG: ModelRouterConfig = {
confidenceThreshold: 0.85,
- maxUncertainty: 0.15,
+ maxUncertainty: envMaxUncertainty() ?? 0.15,
enableCircuitBreaker: true,
circuitBreakerThreshold: 5,
statePath: '.swarm/model-router-state.json',
@@ -336,6 +347,12 @@ const DEFAULT_CONFIG: ModelRouterConfig = {
preferSpeed: true,
};
+// Posterior mean of a Beta(α,β) prior — used by the #2250 escalation guard
+// to detect when the bandit has *learned* the escalation target is worse.
+function priorMean(p: { alpha: number; beta: number }): number {
+ return p.alpha / (p.alpha + p.beta);
+}
+
// ============================================================================
// Model Router Implementation
// ============================================================================
@@ -595,11 +612,38 @@ export class ModelRouter {
const scoreSpread = bestScore - secondScore;
const uncertainty = Math.max(0, 1 - scoreSpread - confidence * 0.5);
- // Escalate if uncertainty is too high
+ // Escalate if uncertainty is too high.
+ //
+ // #2250 — `uncertainty` here is structurally ~0.6-0.7 for low-complexity
+ // tasks (formula: `1 - scoreSpread - confidence*0.5`, where `scoreSpread`
+ // is a raw 0-1 difference between bandit-sampled scores that rarely
+ // exceeds 0.1). With `maxUncertainty = 0.15` the gate fires on
+ // ~every trivial route, promoting `sonnet→opus` and `haiku→sonnet`
+ // even when the Thompson sampler has *already* suppressed the higher
+ // tier (e.g. opus `Beta(3.8, 17.2)`, mean ≈ 0.18). The learned
+ // suppression is computed and then discarded one line later.
+ //
+ // Guard: skip the escalation when EITHER (a) the bandit has confidently
+ // learned the escalation target performs WORSE than the selected model,
+ // OR (b) the bandit has a confident, decent posterior on the selected
+ // model — i.e. the Thompson sampler picked this tier on real evidence,
+ // not a coin flip. Cold-start priors (Beta(1,1), α+β=2, mean=0.5) fail
+ // both checks, so unlearned routers still escalate as before.
let model = bestModel;
if (uncertainty > this.config.maxUncertainty && bestModel !== 'opus') {
- // Escalate to more capable model
- model = bestModel === 'haiku' ? 'sonnet' : 'opus';
+ const escalateTo: ClaudeModel = bestModel === 'haiku' ? 'sonnet' : 'opus';
+ const selectedMean = priorMean(priors[bestModel]);
+ const targetMean = priorMean(priors[escalateTo]);
+ const targetWorse = targetMean < selectedMean - 0.10;
+ // Treat the selected model as trusted once the bandit has accumulated
+ // ~5 effective observations AND its mean is at least 0.45 (neutral-or-
+ // better). Both thresholds chosen to keep cold-start behavior identical
+ // while honoring any non-trivial learning.
+ const selectedSamples = priors[bestModel].alpha + priors[bestModel].beta;
+ const selectedTrusted = selectedSamples >= 5 && selectedMean >= 0.45;
+ if (!targetWorse && !selectedTrusted) {
+ model = escalateTo;
+ }
}
return { model, confidence, uncertainty };
diff --git a/v3/@claude-flow/cli/src/services/worker-daemon.ts b/v3/@claude-flow/cli/src/services/worker-daemon.ts
index ad0e384c34..9b14ab1a3c 100644
--- a/v3/@claude-flow/cli/src/services/worker-daemon.ts
+++ b/v3/@claude-flow/cli/src/services/worker-daemon.ts
@@ -132,6 +132,12 @@ export class WorkerDaemon extends EventEmitter {
// Headless execution support
private headlessExecutor: HeadlessWorkerExecutor | null = null;
private headlessAvailable: boolean = false;
+ // #2251 — Promise that resolves once initHeadlessExecutor() has finished
+ // probing `claude --version` and constructed the executor. The constructor
+ // kicks off init fire-and-forget; without awaiting this on the trigger
+ // path, `ruflo daemon trigger -w <worker>` runs before headlessAvailable
+ // is set and falls through to the local stub in ~2ms.
+ private headlessInitPromise: Promise<void> = Promise.resolve();
// Preserve the original constructor config so we can detect explicit overrides
// during state restoration (R1: constructor config takes priority over stale state)
@@ -202,8 +208,11 @@ export class WorkerDaemon extends EventEmitter {
// Initialize worker states
this.initializeWorkerStates();
- // Initialize headless executor (async, non-blocking)
- this.initHeadlessExecutor().catch((err) => {
+ // Initialize headless executor (async, non-blocking) — capture the
+ // promise so the trigger path (#2251) can await it before checking
+ // `headlessAvailable`. Scheduled fires hit a long-running daemon and
+ // are unaffected; the on-demand `trigger` path was racing this init.
+ this.headlessInitPromise = this.initHeadlessExecutor().catch((err) => {
this.log('warn', `Headless executor init failed: ${err}`);
});
}
@@ -1451,6 +1460,13 @@ export class WorkerDaemon extends EventEmitter {
if (!workerConfig) {
throw new Error(`Unknown worker type: ${type}`);
}
+ // #2251 — wait for headless probe to settle before running. Without
+ // this, on-demand `daemon trigger -w <worker>` races the constructor's
+ // fire-and-forget init and ALWAYS falls through to local mode even
+ // when `claude` is on PATH and scheduled fires of the same worker
+ // use headless correctly. Scheduled fires already wait long enough
+ // (timer + offset) that this is a no-op for them.
+ await this.headlessInitPromise;
return this.executeWorker(workerConfig);
}