@claude-flow/cli 3.32.33 → 3.32.35

package/dist/src/memory/memory-initializer.js

@@ -176,6 +176,32 @@ async function getBridge() {
         return null;
     }
 }
+/**
+ * Build the WAL-sidecar refusal message, naming the bridge failure when one
+ * was recorded.
+ *
+ * The refusal tells the operator to "restore the native better-sqlite3
+ * bridge" but, on its own, gives them no way to discover why it is down —
+ * and the usual cause is a latched init failure inside the bridge, not a
+ * missing better-sqlite3. Appending the recorded reason turns an unactionable
+ * message into a diagnosis.
+ */
+async function walRefusalError(operation) {
+    const base = 'memory database has an active native WAL connection '
+        + '(found -wal/-shm sidecar files) — refusing an unsafe sql.js '
+        + `whole-image ${operation}. Retry once the native writer completes, or `
+        + 'restore the native better-sqlite3 bridge.';
+    try {
+        const bridge = await getBridge();
+        const reason = bridge?.getBridgeFailureReason?.();
+        if (reason)
+            return `${base} Bridge unavailable: ${reason}`;
+    }
+    catch {
+        // Diagnostics must never mask the refusal they annotate.
+    }
+    return base;
+}
 /**
  * Enhanced schema with pattern confidence, temporal decay, versioning
  * Vector embeddings enabled for semantic search
@@ -654,6 +680,64 @@ function saveHNSWMetadata() {
         // Silently fail - metadata save is best-effort
     }
 }
+export function removeHNSWEntriesByLogicalKey(entries, key, namespace) {
+    let removed = 0;
+    for (const [id, entry] of entries) {
+        if (entry.key === key && (entry.namespace ?? 'default') === namespace) {
+            entries.delete(id);
+            removed++;
+        }
+    }
+    return removed;
+}
+function removeHNSWEntriesByKey(key, namespace) {
+    if (!hnswIndex?.entries)
+        return 0;
+    const removed = removeHNSWEntriesByLogicalKey(hnswIndex.entries, key, namespace);
+    if (removed > 0) {
+        saveHNSWMetadata();
+        rebuildSearchIndex();
+    }
+    return removed;
+}
+/**
+ * Remove HNSW metadata whose authoritative SQLite row is no longer active.
+ * Persistent graph nodes may remain physically allocated, but without metadata
+ * they cannot resolve into search results; the next rebuild repopulates only
+ * active rows. Returns the number of searchable vectors invalidated.
+ */
+export async function reconcileHNSWIndex(dbPath) {
+    if (!hnswIndex?.entries)
+        return 0;
+    const effectivePath = dbPath
+        ? path.resolve(dbPath)
+        : path.join(getMemoryRoot(), 'memory.db');
+    if (!fs.existsSync(effectivePath))
+        return 0;
+    try {
+        const initSqlJs = (await import('sql.js')).default;
+        const SQL = await initSqlJs();
+        const db = new SQL.Database(readFileMaybeEncrypted(effectivePath, null));
+        const rows = db.exec(`SELECT id FROM memory_entries WHERE status = 'active'`);
+        const active = new Set((rows[0]?.values ?? []).map((row) => String(row[0])));
+        db.close();
+        let removed = 0;
+        for (const id of hnswIndex.entries.keys()) {
+            if (!active.has(id)) {
+                hnswIndex.entries.delete(id);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            saveHNSWMetadata();
+            rebuildSearchIndex();
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Add entry to HNSW index (with automatic persistence)
  */
@@ -2354,6 +2438,9 @@ export async function storeEntry(options) {
             // Keep HNSW index in sync with bridge-stored entries
             if (bridgeResult.rawEmbedding && bridgeResult.success) {
                 const ns = options.namespace || 'default';
+                // Upsert/resurrection may allocate a new row id. Remove every older
+                // vector for the logical (namespace,key), not merely the newest id.
+                removeHNSWEntriesByKey(options.key, ns);
                 await addToHNSWIndex(bridgeResult.id, bridgeResult.rawEmbedding, {
                     id: bridgeResult.id,
                     key: options.key,
@@ -2382,10 +2469,7 @@ export async function storeEntry(options) {
             return {
                 success: false,
                 id: '',
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image write. Retry once the native writer completes, or ' +
-                    'restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -2462,6 +2546,8 @@ export async function storeEntry(options) {
         // Add to HNSW index for faster future searches
         if (embeddingJson) {
             const embResult = JSON.parse(embeddingJson);
+            if (upsert)
+                removeHNSWEntriesByKey(key, namespace);
             await addToHNSWIndex(id, embResult, {
                 id,
                 key,
@@ -2868,10 +2954,7 @@ export async function getEntry(options) {
             return {
                 success: false,
                 found: false,
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image read/write. Retry once the native writer completes, ' +
-                    'or restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('read/write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -2957,15 +3040,7 @@ export async function deleteEntry(options) {
             // #1122: Bridge path must also invalidate the in-memory HNSW index.
             // Without this, deleted vectors remain as ghost entries in search results.
             if (bridgeResult.deleted && hnswIndex?.entries) {
-                // Remove the entry from the HNSW entries map by key+namespace composite
-                for (const [id, entry] of hnswIndex.entries) {
-                    if (entry?.key === options.key && (entry?.namespace ?? 'default') === (options.namespace ?? 'default')) {
-                        hnswIndex.entries.delete(id);
-                        break;
-                    }
-                }
-                saveHNSWMetadata();
-                rebuildSearchIndex();
+                removeHNSWEntriesByKey(options.key, options.namespace ?? 'default');
             }
             return bridgeResult;
         }
@@ -2994,10 +3069,7 @@ export async function deleteEntry(options) {
                 key,
                 namespace,
                 remainingEntries: 0,
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image write. Retry once the native writer completes, or ' +
-                    'restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -3035,8 +3107,6 @@ export async function deleteEntry(options) {
                 error: `Key '${key}' not found in namespace '${namespace}'`
             };
         }
-        // Capture the entry ID for HNSW cleanup
-        const entryId = String(checkResult[0].values[0][0]);
         // Delete the entry (soft delete by setting status to 'deleted')
         // Also null out the embedding to clean up vector data from SQLite
         db.run(`
@@ -3058,14 +3128,8 @@ export async function deleteEntry(options) {
         // Clean up in-memory HNSW index so ghost vectors don't appear in searches.
         // Remove the entry from the HNSW entries map and invalidate the index.
         // The next search will rebuild the HNSW index from the remaining DB rows.
-        if (hnswIndex?.entries) {
-            hnswIndex.entries.delete(entryId);
-            saveHNSWMetadata();
-            // Invalidate the HNSW index so it rebuilds from DB on next search.
-            // We can't surgically remove a vector from the HNSW graph, so we
-            // clear the entire index; it will be lazily rebuilt from SQLite.
-            rebuildSearchIndex();
-        }
+        if (hnswIndex?.entries)
+            removeHNSWEntriesByKey(key, namespace);
         return {
             success: true,
             deleted: true,

package/dist/src/services/daemon-autostart.js

@@ -8,8 +8,9 @@
  *   - single-instance: only starts when no live daemon holds the pidfile, and
  *     the spawned `daemon start` independently enforces single-instance via its
  *     own lock + checkExistingDaemon() — so a race spawns at most one survivor,
- *   - bounded lifetime: the daemon self-terminates on TTL/idle (12h default,
- *     RUFLO_DAEMON_TTL_SECS) — auto-start never means "runs forever",
+ *   - bounded lifetime: the daemon self-terminates on TTL/idle (12h hard TTL,
+ *     30m idle default; RUFLO_DAEMON_TTL_SECS / RUFLO_DAEMON_IDLE_SECS) —
+ *     auto-start never means "runs forever",
  *   - opt-out: RUFLO_DAEMON_AUTOSTART=0|false|no disables it entirely, OR a
  *     project-local `daemon.autostart: false` in claude-flow.config.json —
  *     the file-based opt-out exists because the env var only reaches a
@@ -85,8 +86,10 @@ export function ensureDaemonRunning(projectRoot, opts = {}) {
     try {
         if (autostartDisabled(projectRoot))
             return { started: false, reason: 'disabled (RUFLO_DAEMON_AUTOSTART=0 or project config)' };
-        // Only in an initialized project (avoid scaffolding a daemon in a random dir).
-        if (!fs.existsSync(path.join(projectRoot, '.claude-flow')) && !fs.existsSync(path.join(projectRoot, '.claude'))) {
+        // `.claude/` belongs to Claude Code and is present in many repositories
+        // that have never initialized Ruflo. Only Ruflo's own state directory is
+        // an authorization signal for spawning a detached background process.
+        if (!fs.existsSync(path.join(projectRoot, '.claude-flow'))) {
             return { started: false, reason: 'not a ruflo project' };
         }
         const alive = (opts.isAlive ?? isDaemonAlive)(projectRoot);

package/dist/src/services/flywheel-receipt.d.ts

@@ -56,6 +56,8 @@ export interface FlywheelReceiptPayload {
     gateVersion: string;
     policySchemaVersion: string;
     safetyEnvelopeRef: string;
+    /** Hash-pinned human relevance anchor used for this evaluation (#2840). */
+    anchorRef?: string;
     requestedProposer: 'auto' | ProposerName;
     effectiveProposer: ProposerName;
     proposerSubstitution?: string;
@@ -86,6 +88,7 @@ export interface CreateReceiptInput {
     gateVersion?: string;
     policySchemaVersion?: string;
     safetyEnvelopeRef: string;
+    anchorRef?: string;
     requestedProposer?: 'auto' | ProposerName;
     effectiveProposer?: ProposerName;
     proposerSubstitution?: string;

package/dist/src/services/flywheel-receipt.js

@@ -206,6 +206,7 @@ export function createFlywheelReceipt(input) {
         gateVersion: input.gateVersion ?? statistics.ruleVersion,
         policySchemaVersion: input.policySchemaVersion ?? 'ruflo.retrieval-policy/v1',
         safetyEnvelopeRef: input.safetyEnvelopeRef,
+        ...(input.anchorRef ? { anchorRef: input.anchorRef } : {}),
         requestedProposer: input.requestedProposer ?? 'local',
         effectiveProposer: input.effectiveProposer ?? 'local',
         ...(input.proposerSubstitution ? { proposerSubstitution: input.proposerSubstitution } : {}),

package/dist/src/services/harness-flywheel-runtime.d.ts

@@ -39,6 +39,9 @@ export declare function runFlywheelWorker(projectRoot: string, opts?: {
     allowSubstitutionPromotion?: boolean;
     maxConcurrency?: number;
     evaluationTimeoutMs?: number;
+    anchorPath?: string;
+    anchorHash?: string;
+    anchorManifestPath?: string;
 }): Promise<FlywheelResult>;
 /**
  * Run ONE live COMPOUNDING generation against the persisted lineage (ADR-176
@@ -52,5 +55,8 @@ export declare function runFlywheelGenerationWorker(projectRoot: string, opts?:
     sample?: number;
     optInOverride?: boolean;
     now?: number;
+    anchorPath?: string;
+    anchorHash?: string;
+    anchorManifestPath?: string;
 }): Promise<GenerationResult>;
 //# sourceMappingURL=harness-flywheel-runtime.d.ts.map

package/dist/src/services/harness-flywheel-runtime.js

@@ -7,23 +7,10 @@
 import { harnessLoopOptedIn } from './harness-worker.js';
 import { DEFAULT_CONFIG, retrievalPolicyNeighbors, runFlywheelTick, } from './harness-flywheel.js';
 import { runFlywheelGeneration, checkServedChampionDrift } from './harness-flywheel-generations.js';
-import { loadFrozenHumanEval } from './harness-frozen-eval.js';
+import { loadEffectiveFlywheelAnchor } from './harness-project-anchor.js';
 import { proposeFlywheelCandidates, } from './flywheel-proposer.js';
 import { sha256Ref } from './flywheel-receipt.js';
 import { evaluatePolicyRequest } from './policy-runtime.js';
-/** The human-labeled ADR-081 anchor — the never-regress relevance set. */
-const ANCHOR = [
-    ['how was the Opus model alias fixed', ['opus 4.8', 'opus alias', 'opus model alias', '#2232']],
-    ['self-learning wiring task-completed pretrain', ['self-learning', 'adr-074', 'self learning', '#2245', 'task-completed']],
-    ['deterministic codemod engine var-to-const', ['deterministic tier-1 codemod', 'adr-143', 'codemod', 'var-to-const']],
-    ['MCP server orphan leak parent-death', ['mcp orphan', 'mcp servers orphan', 'parent-death', '#2234', 'orphan on every claude']],
-    ['unified learning stats aggregator', ['unified learning-stats', 'adr-075', 'unified learning stats']],
-    ['structured distillation 4-field schema', ['structured distillation', 'adr-076', '4-field schema']],
-    ['SQL injection migrate.ts table identifier', ['sql injection', 'shell injection', 'migrate.ts', 'agentdb', 'cve']],
-    ['recall@k HNSW benchmark harness', ['hnsw', 'memory-recall', 'benchmark suite', 'recall@k', 'benchmark intelligence']],
-    ['Q-learning encoder keyword block', ['q-state encoder', 'route q-state', 'keyword block', '#2239', 'q-encoder']],
-    ['security hardening crypto random IDs', ['cwe-347', 'crypto.randomuuid', 'security fix', 'random id', 'crypto random']],
-].map(([q, labels], i) => ({ id: `q${String(i).padStart(2, '0')}`, input: { id: `q${String(i).padStart(2, '0')}`, q: q }, expected: labels }));
 /**
  * The ADR-322 retrieval safety envelope.
  *
@@ -99,6 +86,11 @@ export async function runFlywheelWorker(projectRoot, opts = {}) {
             ...(applier.activeChampion(projectRoot)?.params ?? {}),
         };
         const safetyEnvelope = retrievalSafetyEnvelope(opts.safetyEnvelopeRef);
+        const anchor = loadEffectiveFlywheelAnchor(projectRoot, {
+            anchorPath: opts.anchorPath ?? process.env.RUFLO_FLYWHEEL_ANCHOR_PATH,
+            anchorHash: opts.anchorHash ?? process.env.RUFLO_FLYWHEEL_ANCHOR_HASH,
+            manifestPath: opts.anchorManifestPath ?? process.env.RUFLO_FLYWHEEL_ANCHOR_MANIFEST,
+        });
         // CLI flag opts.proposer takes precedence over RUFLO_FLYWHEEL_PROPOSER.
         const proposerMode = opts.proposer
             ?? (process.env.RUFLO_FLYWHEEL_PROPOSER ?? 'auto');
@@ -134,7 +126,8 @@ export async function runFlywheelWorker(projectRoot, opts = {}) {
                 const r = await tool.handler({ action: 'search', query, mode: 'hybrid', limit: 5, rerank: false, ...cfg });
                 return (r.results || []).slice(0, 5).map((m) => ({ id: m?.id ?? '', name: m?.name ?? '' }));
             },
-            anchorTasks: ANCHOR,
+            anchorTasks: anchor.tasks,
+            anchorRef: anchor.anchorRef,
             activeParams: () => baseline,
             sample: opts.sample ?? 40,
             now: opts.now,
@@ -172,16 +165,23 @@ export async function runFlywheelGenerationWorker(projectRoot, opts = {}) {
         const tool = neural.neuralTools.find((t) => t.name === 'neural_patterns');
         if (!tool)
             return { ran: false, reason: 'neural_patterns tool unavailable', generation: 0 };
-        // Load the FROZEN, hashed, public human eval set (throws if it has drifted).
-        const frozen = loadFrozenHumanEval();
+        const anchor = loadEffectiveFlywheelAnchor(projectRoot, {
+            anchorPath: opts.anchorPath ?? process.env.RUFLO_FLYWHEEL_ANCHOR_PATH,
+            anchorHash: opts.anchorHash ?? process.env.RUFLO_FLYWHEEL_ANCHOR_HASH,
+            manifestPath: opts.anchorManifestPath ?? process.env.RUFLO_FLYWHEEL_ANCHOR_MANIFEST,
+        });
         const deps = {
             getPatterns: () => neural.getStorePatterns(),
             search: async (query, cfg) => {
                 const r = await tool.handler({ action: 'search', query, mode: 'hybrid', limit: 5, rerank: false, ...cfg });
                 return (r.results || []).slice(0, 5).map((m) => ({ id: m?.id ?? '', name: m?.name ?? '' }));
             },
-            anchorTasks: frozen.tasks,
-            humanEvalHash: frozen.corpusHash,
+            anchorTasks: anchor.tasks.map((task) => ({
+                id: task.id,
+                q: task.input.q,
+                labels: task.expected,
+            })),
+            humanEvalHash: anchor.anchorRef,
             sample: opts.sample ?? 120,
             now: opts.now ?? Date.now(),
         };

package/dist/src/services/harness-flywheel.d.ts

@@ -30,6 +30,8 @@ export interface FlywheelDeps {
     lineageId?: string;
     evaluationRunId?: string;
     safetyEnvelopeRef?: string;
+    /** Hash of the project-specific human-labelled objective. */
+    anchorRef?: string;
     requestedProposer?: 'auto' | 'local' | 'darwin';
     effectiveProposer?: 'local' | 'darwin';
     proposerSubstitution?: string;

package/dist/src/services/harness-flywheel.js

@@ -210,6 +210,7 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
             expectedLedgerHead: txState.ledgerHead,
             candidatePolicy: candidate,
             safetyEnvelopeRef,
+            anchorRef: deps.anchorRef,
             requestedProposer: deps.requestedProposer ?? 'local',
             effectiveProposer: deps.effectiveProposer ?? 'local',
             proposerSubstitution: deps.proposerSubstitution,

package/dist/src/services/harness-project-anchor.d.ts

@@ -0,0 +1,23 @@
+import type { AnchorTask } from './harness-flywheel.js';
+export declare const PROJECT_ANCHOR_SCHEMA = "ruflo.flywheel-anchor/v1";
+export declare const PROJECT_ANCHOR_MANIFEST_SCHEMA = "ruflo.flywheel-anchor-manifest/v1";
+export declare const DEFAULT_PROJECT_ANCHOR_MANIFEST: string;
+export interface ProjectAnchorManifest {
+    schemaVersion: typeof PROJECT_ANCHOR_MANIFEST_SCHEMA;
+    path: string;
+    sha256: string;
+}
+export interface FlywheelAnchorSelection {
+    version: string;
+    anchorRef: string;
+    tasks: AnchorTask[];
+    source: 'project' | 'ruflo-built-in';
+    path?: string;
+}
+export interface LoadFlywheelAnchorOptions {
+    anchorPath?: string;
+    anchorHash?: string;
+    manifestPath?: string;
+}
+export declare function loadEffectiveFlywheelAnchor(projectRoot: string, options?: LoadFlywheelAnchorOptions): FlywheelAnchorSelection;
+//# sourceMappingURL=harness-project-anchor.d.ts.map

package/dist/src/services/harness-project-anchor.js

@@ -0,0 +1,129 @@
+/**
+ * Project-local, hash-pinned flywheel anchors (#2840).
+ *
+ * Downstream repositories must be evaluated against their own labelled
+ * retrieval tasks. Silently using Ruflo's development-history benchmark makes
+ * the objective flat and indistinguishable from "already optimal", so foreign
+ * projects fail closed unless they supply a pinned anchor manifest.
+ */
+import { existsSync, readFileSync, realpathSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
+import { FROZEN_HUMAN_EVAL_HASH, loadFrozenHumanEval, humanEvalHash, } from './harness-frozen-eval.js';
+export const PROJECT_ANCHOR_SCHEMA = 'ruflo.flywheel-anchor/v1';
+export const PROJECT_ANCHOR_MANIFEST_SCHEMA = 'ruflo.flywheel-anchor-manifest/v1';
+export const DEFAULT_PROJECT_ANCHOR_MANIFEST = join('.claude', 'eval', 'flywheel-anchor.manifest.json');
+function normalizeHash(value) {
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.startsWith('sha256:') ? trimmed : `sha256:${trimmed}`;
+}
+function containedPath(projectRoot, requested) {
+    const root = realpathSync(resolve(projectRoot));
+    const absolute = isAbsolute(requested) ? resolve(requested) : resolve(root, requested);
+    const lexical = relative(root, absolute);
+    if (lexical === '..' || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+        throw new Error('flywheel anchor path must stay inside project root');
+    }
+    const actual = realpathSync(absolute);
+    const physical = relative(root, actual);
+    if (physical === '..' || physical.startsWith(`..${sep}`) || isAbsolute(physical)) {
+        throw new Error('flywheel anchor symlink escapes project root');
+    }
+    return actual;
+}
+function parseTasks(path) {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed.schemaVersion && parsed.schemaVersion !== PROJECT_ANCHOR_SCHEMA) {
+        throw new Error(`unsupported flywheel anchor schema: ${parsed.schemaVersion}`);
+    }
+    if (!Array.isArray(parsed.tasks) || parsed.tasks.length < 4) {
+        throw new Error('project flywheel anchor requires at least 4 labelled tasks');
+    }
+    const ids = new Set();
+    for (const [index, task] of parsed.tasks.entries()) {
+        if (!task || typeof task.id !== 'string' || !/^[A-Za-z0-9._-]{1,128}$/.test(task.id)) {
+            throw new Error(`invalid anchor task id at index ${index}`);
+        }
+        if (ids.has(task.id))
+            throw new Error(`duplicate anchor task id: ${task.id}`);
+        ids.add(task.id);
+        if (typeof task.q !== 'string' || task.q.trim().length === 0) {
+            throw new Error(`anchor task ${task.id} has no query`);
+        }
+        if (!Array.isArray(task.labels) || task.labels.length === 0 || task.labels.some((label) => typeof label !== 'string' || !label.trim())) {
+            throw new Error(`anchor task ${task.id} requires non-empty string labels`);
+        }
+    }
+    return { version: parsed.version ?? 'project-anchor-v1', tasks: parsed.tasks };
+}
+function toSelection(path, expectedHash) {
+    const parsed = parseTasks(path);
+    const actualHash = humanEvalHash(parsed.tasks);
+    if (actualHash !== normalizeHash(expectedHash)) {
+        throw new Error(`project flywheel anchor hash mismatch (got ${actualHash}, pinned ${normalizeHash(expectedHash)})`);
+    }
+    return {
+        version: parsed.version,
+        anchorRef: actualHash,
+        source: 'project',
+        path,
+        tasks: parsed.tasks.map((task) => ({
+            id: task.id,
+            input: { id: task.id, q: task.q },
+            expected: task.labels,
+        })),
+    };
+}
+function isRufloRepository(projectRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+        const repository = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+        return ['claude-flow', 'ruflo', '@claude-flow/cli'].includes(pkg.name ?? '')
+            && /github\.com[/:]ruvnet\/(?:ruflo|claude-flow)(?:\.git)?$/i.test(repository ?? '');
+    }
+    catch {
+        return false;
+    }
+}
+export function loadEffectiveFlywheelAnchor(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    if (!!options.anchorPath !== !!options.anchorHash) {
+        throw new Error('anchorPath and anchorHash must be supplied together');
+    }
+    if (options.anchorPath && options.anchorHash) {
+        return toSelection(containedPath(root, options.anchorPath), options.anchorHash);
+    }
+    const manifestCandidate = options.manifestPath ?? DEFAULT_PROJECT_ANCHOR_MANIFEST;
+    const manifestPath = isAbsolute(manifestCandidate)
+        ? manifestCandidate
+        : resolve(root, manifestCandidate);
+    if (existsSync(manifestPath)) {
+        const containedManifest = containedPath(root, manifestPath);
+        const manifest = JSON.parse(readFileSync(containedManifest, 'utf8'));
+        if (manifest.schemaVersion !== PROJECT_ANCHOR_MANIFEST_SCHEMA) {
+            throw new Error(`unsupported flywheel anchor manifest schema: ${manifest.schemaVersion}`);
+        }
+        if (typeof manifest.path !== 'string' || typeof manifest.sha256 !== 'string') {
+            throw new Error('flywheel anchor manifest requires path and sha256');
+        }
+        // Manifest-relative paths are easier to relocate while remaining
+        // repository-contained; project-relative paths remain supported.
+        const manifestRelative = resolve(dirname(containedManifest), manifest.path);
+        const requested = existsSync(manifestRelative) ? manifestRelative : resolve(root, manifest.path);
+        return toSelection(containedPath(root, requested), manifest.sha256);
+    }
+    if (isRufloRepository(root) || process.env.RUFLO_FLYWHEEL_ALLOW_BUILTIN_ANCHOR === '1') {
+        const frozen = loadFrozenHumanEval();
+        return {
+            version: frozen.version,
+            anchorRef: FROZEN_HUMAN_EVAL_HASH,
+            source: 'ruflo-built-in',
+            tasks: frozen.tasks.map((task) => ({
+                id: task.id,
+                input: { id: task.id, q: task.q },
+                expected: task.labels,
+            })),
+        };
+    }
+    throw new Error(`project-local flywheel anchor required; create ${DEFAULT_PROJECT_ANCHOR_MANIFEST} or pass anchorPath + anchorHash`);
+}
+//# sourceMappingURL=harness-project-anchor.js.map

package/dist/src/services/learned-routing.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Discriminative routing-pattern learner (#2839).
+ *
+ * Outcomes are labelled by the agent that actually completed the task. The
+ * previous implementation collapsed every successful task for an agent into
+ * one insertion-ordered Set and kept the first 50 words forever. This module
+ * ranks terms by within-agent support, cross-agent rarity, outcome quality,
+ * and discriminative share. Generic terms therefore lose to stable,
+ * agent-specific evidence, and later outcomes can replace earlier noise.
+ */
+export interface LearnedRoutingOutcome {
+    task: string;
+    agent: string;
+    success: boolean;
+    quality: number;
+    keywords: string[];
+    timestamp: string;
+}
+export interface LearnedRoutingPattern {
+    keywords: string[];
+    agents: string[];
+    source: 'learned';
+    support: number;
+    reliability: number;
+}
+export interface LearnedRoutingOptions {
+    maxKeywords?: number;
+    minAgentOutcomes?: number;
+    minKeywordSupport?: number;
+    minOutcomeQuality?: number;
+    minDiscriminativeShare?: number;
+}
+export declare function buildLearnedRoutingPatterns(outcomes: LearnedRoutingOutcome[], options?: LearnedRoutingOptions): Record<string, LearnedRoutingPattern>;
+//# sourceMappingURL=learned-routing.d.ts.map

package/dist/src/services/learned-routing.js

@@ -0,0 +1,85 @@
+/**
+ * Discriminative routing-pattern learner (#2839).
+ *
+ * Outcomes are labelled by the agent that actually completed the task. The
+ * previous implementation collapsed every successful task for an agent into
+ * one insertion-ordered Set and kept the first 50 words forever. This module
+ * ranks terms by within-agent support, cross-agent rarity, outcome quality,
+ * and discriminative share. Generic terms therefore lose to stable,
+ * agent-specific evidence, and later outcomes can replace earlier noise.
+ */
+const finiteUnit = (value) => Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+export function buildLearnedRoutingPatterns(outcomes, options = {}) {
+    const maxKeywords = Math.max(1, Math.min(options.maxKeywords ?? 50, 100));
+    const minAgentOutcomes = Math.max(1, options.minAgentOutcomes ?? 2);
+    const minKeywordSupport = Math.max(1, options.minKeywordSupport ?? 2);
+    const minOutcomeQuality = finiteUnit(options.minOutcomeQuality ?? 0.65);
+    const minDiscriminativeShare = finiteUnit(options.minDiscriminativeShare ?? 0.6);
+    const accepted = outcomes.filter((outcome) => outcome.success
+        && typeof outcome.agent === 'string'
+        && outcome.agent.length > 0
+        && finiteUnit(outcome.quality) >= minOutcomeQuality
+        && Array.isArray(outcome.keywords)
+        && outcome.keywords.length > 0);
+    const agents = [...new Set(accepted.map((outcome) => outcome.agent))].sort();
+    if (agents.length === 0)
+        return {};
+    const agentOutcomes = new Map();
+    const evidence = new Map();
+    const globalSupport = new Map();
+    const agentDocumentFrequency = new Map();
+    for (const agent of agents) {
+        const rows = accepted.filter((outcome) => outcome.agent === agent);
+        agentOutcomes.set(agent, rows);
+        const perKeyword = new Map();
+        for (const row of rows) {
+            const unique = new Set(row.keywords.map((keyword) => keyword.trim().toLowerCase()).filter(Boolean));
+            for (const keyword of unique) {
+                const current = perKeyword.get(keyword) ?? { support: 0, qualityTotal: 0 };
+                current.support++;
+                current.qualityTotal += finiteUnit(row.quality);
+                perKeyword.set(keyword, current);
+                globalSupport.set(keyword, (globalSupport.get(keyword) ?? 0) + 1);
+            }
+        }
+        evidence.set(agent, perKeyword);
+        for (const keyword of perKeyword.keys()) {
+            agentDocumentFrequency.set(keyword, (agentDocumentFrequency.get(keyword) ?? 0) + 1);
+        }
+    }
+    const patterns = {};
+    for (const agent of agents) {
+        const rows = agentOutcomes.get(agent) ?? [];
+        if (rows.length < minAgentOutcomes)
+            continue;
+        const ranked = [...(evidence.get(agent) ?? new Map()).entries()]
+            .filter(([, item]) => item.support >= minKeywordSupport)
+            .map(([keyword, item]) => {
+            const totalSupport = globalSupport.get(keyword) ?? item.support;
+            const discriminativeShare = item.support / Math.max(1, totalSupport);
+            const documentFrequency = agentDocumentFrequency.get(keyword) ?? 1;
+            const idf = Math.log(1 + agents.length / documentFrequency);
+            const withinAgentSupport = item.support / rows.length;
+            const meanQuality = item.qualityTotal / item.support;
+            return {
+                keyword,
+                discriminativeShare,
+                score: withinAgentSupport * meanQuality * idf * discriminativeShare,
+            };
+        })
+            .filter((item) => item.discriminativeShare >= minDiscriminativeShare)
+            .sort((a, b) => b.score - a.score || a.keyword.localeCompare(b.keyword))
+            .slice(0, maxKeywords);
+        if (ranked.length === 0)
+            continue;
+        patterns[`learned-${agent}`] = {
+            keywords: ranked.map((item) => item.keyword),
+            agents: [agent],
+            source: 'learned',
+            support: rows.length,
+            reliability: rows.reduce((sum, row) => sum + finiteUnit(row.quality), 0) / rows.length,
+        };
+    }
+    return patterns;
+}
+//# sourceMappingURL=learned-routing.js.map