@claude-flow/cli 3.25.5 → 3.26.0

package/dist/src/funnel/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Funnel type definitions — ADR-301..310.
+ *
+ * The funnel is the ruflo → Cognitum lifecycle system: promotional status
+ * surface (ADR-301), post-init enrollment (ADR-302), credit-exhaustion
+ * recovery (ADR-303), governed by consent receipts (ADR-302), control
+ * precedence (ADR-305), and the governance/privacy rules of ADR-309.
+ *
+ * Everything in this module is local-only: no code path here performs
+ * network I/O. Events are queued locally and only when telemetry consent
+ * is granted (ADR-308 failure policy: telemetry never blocks the CLI).
+ */
+export type FunnelDisclosureState = 'never_seen' | 'disclosed_enabled' | 'disclosed_disabled';
+export interface DisclosureRecord {
+    state: FunnelDisclosureState;
+    /** ISO timestamp of the first render of the disclosure text. */
+    firstShownAt: string | null;
+}
+export type FunnelMessageClass = 'educational' | 'promotional' | 'disclosure';
+export interface FunnelMessage {
+    id: string;
+    schemaVersion: 1;
+    text: string;
+    /** Optional link; must pass the in-code host allowlist or the message is dropped. */
+    url?: string;
+    class: FunnelMessageClass;
+    /** ISO timestamp; expired messages leave the rotation immediately. */
+    expiresAt?: string;
+}
+export interface PromoRow {
+    text: string;
+    kind: 'disclosure' | FunnelMessageClass | 'insight';
+    url?: string;
+}
+export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips';
+export interface ConsentReceipt {
+    granted: boolean;
+    policyVersion: number;
+    /** ISO timestamp of the decision; null = never asked. */
+    at: string | null;
+    surface: string | null;
+}
+export type ConsentFile = Partial<Record<ConsentDomain, ConsentReceipt>>;
+/** Bump when the meaning of a consent domain changes materially (ADR-302). */
+export declare const CONSENT_POLICY_VERSION = 1;
+export type FunnelDecisionSource = 'env' | 'enterprise-policy' | 'user-config' | 'project-config' | 'package-default' | 'remote-policy' | 'disclosure-declined';
+export interface FunnelEnabledDecision {
+    enabled: boolean;
+    decidedBy: FunnelDecisionSource;
+}
+export declare enum CreditErrorCode {
+    /** Cognitum ledger says balance is spent — the ONLY funnel trigger. */
+    COGNITUM_CREDIT_EXHAUSTED = "COGNITUM_CREDIT_EXHAUSTED",
+    /** Upstream provider's own quota, not Cognitum credits. */
+    PROVIDER_QUOTA_EXHAUSTED = "PROVIDER_QUOTA_EXHAUSTED",
+    PROVIDER_RATE_LIMITED = "PROVIDER_RATE_LIMITED",
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+}
+export interface NormalizedCreditError {
+    code: CreditErrorCode | null;
+    /** 1 only when an explicit machine-readable provider code mapped; else 0. */
+    confidence: 0 | 1;
+    retryable: boolean;
+    /** Original provider error, preserved verbatim for --verbose paths. */
+    cause?: unknown;
+}
+export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled';
+export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion';
+export interface FunnelEvent {
+    schemaVersion: 1;
+    event: FunnelEventName;
+    surface: FunnelSurface;
+    release: string;
+    region?: string;
+    pseudonymousId?: string;
+    /**
+     * Message id for promo_impression / promo_open — lets the analyst
+     * attribute clicks + impressions to a specific rotation entry without
+     * carrying prompt/URL/PII data.
+     */
+    messageId?: string;
+    /** Daily bucket ("2026-07-10") — full timestamps are never recorded. */
+    timestampBucket: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/funnel/types.js

@@ -0,0 +1,26 @@
+/**
+ * Funnel type definitions — ADR-301..310.
+ *
+ * The funnel is the ruflo → Cognitum lifecycle system: promotional status
+ * surface (ADR-301), post-init enrollment (ADR-302), credit-exhaustion
+ * recovery (ADR-303), governed by consent receipts (ADR-302), control
+ * precedence (ADR-305), and the governance/privacy rules of ADR-309.
+ *
+ * Everything in this module is local-only: no code path here performs
+ * network I/O. Events are queued locally and only when telemetry consent
+ * is granted (ADR-308 failure policy: telemetry never blocks the CLI).
+ */
+/** Bump when the meaning of a consent domain changes materially (ADR-302). */
+export const CONSENT_POLICY_VERSION = 1;
+// ─── ADR-303: credit error taxonomy ─────────────────────────────────────────
+export var CreditErrorCode;
+(function (CreditErrorCode) {
+    /** Cognitum ledger says balance is spent — the ONLY funnel trigger. */
+    CreditErrorCode["COGNITUM_CREDIT_EXHAUSTED"] = "COGNITUM_CREDIT_EXHAUSTED";
+    /** Upstream provider's own quota, not Cognitum credits. */
+    CreditErrorCode["PROVIDER_QUOTA_EXHAUSTED"] = "PROVIDER_QUOTA_EXHAUSTED";
+    CreditErrorCode["PROVIDER_RATE_LIMITED"] = "PROVIDER_RATE_LIMITED";
+    CreditErrorCode["AUTHENTICATION_FAILED"] = "AUTHENTICATION_FAILED";
+    CreditErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+})(CreditErrorCode || (CreditErrorCode = {}));
+//# sourceMappingURL=types.js.map

package/dist/src/init/executor.js

@@ -341,7 +341,11 @@ function mergeSettingsForUpgrade(existing) {
     // load the ONNX model on every fire (~1s); Claude Code times out and hides
     // the status bar (#2450). The migration replaces the whole command with
     // NEW_STATUSLINE_CMD which invokes the local helper directly via `node -e`.
-    const BROKEN_STATUSLINE_RE = /(?:npx\s+(?:--?\S+\s+)*)?@?claude-flow(?:\/cli)?(?:@\S+)?\s+hooks\s+statusline/;
+    // Flag-list repetition bounded at 10 (real invocations never carry more) —
+    // an unbounded `*` here is exponential-backtracking-prone (CodeQL
+    // js/redos): a crafted settings.json command string with dozens of
+    // dash-token repetitions can hang this check for minutes.
+    const BROKEN_STATUSLINE_RE = /(?:npx\s+(?:--?\S+\s+){0,10})?@?claude-flow(?:\/cli)?(?:@\S+)?\s+hooks\s+statusline/;
     const existingStatusLine = existing.statusLine;
     if (existingStatusLine) {
         const existingCmd = typeof existingStatusLine.command === 'string' ? existingStatusLine.command : '';
@@ -361,7 +365,8 @@ function mergeSettingsForUpgrade(existing) {
     // We walk each hook event's `hooks[]` and swap any command matching the
     // broken pattern for the local-helper form. Idempotent: re-running this
     // migration on already-correct settings is a no-op.
-    const BROKEN_HOOK_RE = /npx\s+(?:--?\S+\s+)*@?claude-flow\/cli@latest\s+hooks\s+(\S+)/;
+    // Bounded for the same reason as BROKEN_STATUSLINE_RE above (CodeQL js/redos).
+    const BROKEN_HOOK_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+hooks\s+(\S+)/;
     const localHookCmd = (sub) => {
         // POSIX form mirrors settings-generator.ts::hookCmd() exactly.
         // Windows users hit a separate code path (cmd /c …) — Claude Code on
@@ -456,7 +461,8 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         // 0. ALWAYS update critical helpers (force overwrite)
         const sourceHelpersForUpgrade = findSourceHelpersDir();
         if (sourceHelpersForUpgrade) {
-            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+            // Keep in sync with helper-refresh.ts:CRITICAL_HELPERS.
+            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs'];
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -807,7 +813,7 @@ async function writeSettings(targetDir, options, result) {
  * "same MCP server twice under two different prefixes" duplication the
  * issue describes.
  *
- * Returns the path of the file that already declares `ruflo` (so we can
+ * Returns the path of the file that already declares `ruflo`/`claude-flow` (so we can
  * surface it in the skipped-message), or null if none found.
  */
 function detectExistingRufloMCP(targetDir) {
@@ -840,10 +846,9 @@ function detectExistingRufloMCP(targetDir) {
             if (!parsed || typeof parsed !== 'object')
                 continue;
             // (a) Top-level mcpServers (legacy / global form).
-            // #2207: accept BOTH the old 'ruflo' key AND the new 'claude-flow' key so that
-            // a prior install with either key is correctly detected as already-initialized.
-            // This also avoids the reverse problem: after #2206 fixed the generator to write
-            // 'claude-flow', a second `ruflo init` must still recognise the existing install.
+            // Accept BOTH names so init does not add a second server for the same
+            // binary when a project carries a pre-rename `claude-flow` registration
+            // and the current generator would write `ruflo` (#2612).
             if (parsed.mcpServers && typeof parsed.mcpServers === 'object') {
                 const servers = parsed.mcpServers;
                 // #2369: also recognise the legacy dist-tag keys generated by
@@ -859,10 +864,9 @@ function detectExistingRufloMCP(targetDir) {
             }
             // (b) #1840: Claude Code project-scoped registrations under
             //     parsed.projects[<projectPath>].mcpServers. Match by
-            //     normalized path against targetDir or any of its ancestors so
-            //     a `claude mcp add claude-flow` (or legacy `ruflo`) in this repo is
+            //     normalized path against targetDir or any of its ancestors so an
+            //     existing `claude-flow` or `ruflo` registration in this repo is
             //     detected even when Claude stored the key with different casing/slash style.
-            // #2207: accept both keys here too.
             if (parsed.projects && typeof parsed.projects === 'object') {
                 for (const [projectKey, projectVal] of Object.entries(parsed.projects)) {
                     if (!projectVal || typeof projectVal !== 'object')
@@ -925,16 +929,18 @@ async function writeMCPConfig(targetDir, options, result) {
         result.skipped.push('.mcp.json');
         return;
     }
-    // #1779 — Skip writing if the user already has a `ruflo`-keyed MCP
-    // server registered elsewhere (parent .mcp.json, ~/.claude.json, etc).
-    // Writing our `claude-flow`-keyed entry on top of that produces the
-    // duplicate-registration the issue describes (~250 duplicate tools).
-    // Force-mode (`--force`) bypasses this guard for users who actually
-    // want both registrations.
+    // #1779/#2612 — Skip writing if the user already has this MCP server
+    // registered elsewhere (parent .mcp.json, ~/.claude.json, etc). The
+    // canonical key is `claude-flow` (per #2206 — matches mcp__claude-flow__*
+    // plugin tool refs); a stray `ruflo`-keyed entry pointing at the same
+    // binary is the legacy-duplicate form that #2612 healed. Writing our
+    // fresh `claude-flow` entry on top of either variant starts the same
+    // binary twice under two tool namespaces. Force-mode (`--force`)
+    // bypasses this guard for users who actually want both registrations.
     if (!options.force) {
         const existingRufloPath = detectExistingRufloMCP(targetDir);
         if (existingRufloPath) {
-            result.skipped.push(`.mcp.json (existing 'ruflo' MCP registration found at ${existingRufloPath} — would create duplicate; pass --force to write anyway)`);
+            result.skipped.push(`.mcp.json (existing ruflo/claude-flow MCP registration found at ${existingRufloPath} — would create duplicate; pass --force to write anyway)`);
             return;
         }
     }
@@ -1880,7 +1886,7 @@ npx @claude-flow/cli@latest hive-mind consensus --propose "task"
 ### MCP Server Setup
 \`\`\`bash
 # Add Ruflo MCP
-claude mcp add ruflo -- npx -y ruflo@latest
+claude mcp add ruflo -- npx -y ruflo@latest mcp start
 
 # Optional servers
 claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start

package/dist/src/init/helper-refresh.d.ts

@@ -1,5 +1,10 @@
 export declare const HELPERS_STAMP_FILE = ".helpers-version";
-/** ruflo-owned helpers that carry hook logic and must track the package version. */
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
 export declare const CRITICAL_HELPERS: string[];
 /** Installed @claude-flow/cli version — the value the helpers are stamped with. */
 export declare function getInstalledCliVersion(): string;
@@ -9,8 +14,34 @@ export declare function getInstalledCliVersion(): string;
  * stamp read + string compare (sub-ms); the copy runs at most once per version
  * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
  * existing hook-handler.cjs — never creates files in an unrelated directory).
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) against THIS project directory
+ * would see its own older version != the project's newer stamp and silently
+ * overwrite hand-fixed `hook-handler.cjs`/`intelligence.cjs` with its own
+ * older, already-superseded bundled copies. Comparing with `semver.gt`
+ * instead of `!==` makes that impossible: an older or equal installed
+ * version is always a no-op, regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
+ * THIS repo's actual current `.claude/helpers` + its real Ed25519 signature —
+ * fine for production (that coupling to the real source IS the point), but
+ * it means a test exercising that path for real would only pass when this
+ * repo's manifest happens to be currently re-signed, which is a separately-
+ * gated, occasionally-stale publish-time step. `sourceDirOverride` +
+ * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash →
+ * copy logic without depending on that.
  */
-export declare function autoRefreshHelpersIfStale(cwd: string): Promise<{
+export declare function autoRefreshHelpersIfStale(cwd: string, opts?: {
+    sourceDirOverride?: string;
+    pubkeyPemOverride?: string;
+    versionOverride?: string;
+}): Promise<{
     refreshed: boolean;
     from?: string;
     to?: string;

package/dist/src/init/helper-refresh.js

@@ -17,11 +17,55 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
+import * as semver from 'semver';
 import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Walk up from `startDir` to the nearest ancestor whose `package.json` names
+ * `@claude-flow/cli` — depth-independent, unlike a hardcoded `'..','..',
+ * '..'`. That fixed count assumed this module always runs compiled, three
+ * levels under the package root (`dist/src/init/helper-refresh.js`); it
+ * silently breaks whenever the module runs from a different depth — e.g.
+ * loaded straight from `src/init/helper-refresh.ts` (one level shallower:
+ * ts-node, tsx, or a test runner that transforms TS in place rather than
+ * requiring a prior `tsc` build). When that happened here, BOTH
+ * `getInstalledCliVersion()` silently fell back to the placeholder `'0.0.0'`
+ * AND `findPackageHelpersDir()` silently failed to resolve the real package
+ * helpers dir — with no error surfaced, just wrong values propagating into
+ * version-comparison and refresh-source-selection logic. Real ceiling on the
+ * walk (`maxUp`) so a package.json-less filesystem can't loop forever.
+ */
+function findPackageRoot(startDir, maxUp = 6) {
+    let dir = startDir;
+    for (let i = 0; i < maxUp; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+            if (pkg && pkg.name === '@claude-flow/cli')
+                return dir;
+        }
+        catch { /* no package.json here, or unreadable — keep climbing */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return null;
+}
 export const HELPERS_STAMP_FILE = '.helpers-version';
-/** ruflo-owned helpers that carry hook logic and must track the package version. */
-export const CRITICAL_HELPERS = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
+export const CRITICAL_HELPERS = [
+    'auto-memory-hook.mjs',
+    'hook-handler.cjs',
+    'intelligence.cjs',
+    // statusline.cjs is here so the funnel disclosure row (ADR-301) reaches
+    // existing installs on the next `ruflo` command, not only fresh `ruflo init`.
+    'statusline.cjs',
+];
 /** Installed @claude-flow/cli version — the value the helpers are stamped with. */
 export function getInstalledCliVersion() {
     try {
@@ -30,9 +74,11 @@ export function getInstalledCliVersion() {
         return String(pkg.version || '0.0.0');
     }
     catch {
-        // dist/src/init → package root
+        const root = findPackageRoot(__dirname);
+        if (!root)
+            return '0.0.0';
         try {
-            const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
             return String(pkg.version || '0.0.0');
         }
         catch {
@@ -49,7 +95,9 @@ function findPackageHelpersDir() {
         candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
     }
     catch { /* not resolvable */ }
-    candidates.push(path.resolve(__dirname, '..', '..', '..', '.claude', 'helpers'));
+    const root = findPackageRoot(__dirname);
+    if (root)
+        candidates.push(path.join(root, '.claude', 'helpers'));
     for (const c of candidates) {
         if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
             return c;
@@ -67,13 +115,16 @@ function findPackageHelpersDir() {
  * fallback needs no manifest — that content comes from the CLI's own compiled
  * code, which is already the trust root.
  */
-async function writeCriticalHelpers(helpersDir, version) {
-    const source = findPackageHelpersDir();
+async function writeCriticalHelpers(helpersDir, version, opts = {}) {
+    const source = opts.sourceDirOverride ?? findPackageHelpersDir();
     if (source) {
-        // 1. Verify the signed manifest against the baked public key.
+        // 1. Verify the signed manifest against the baked public key (or, in
+        // tests, an injected throwaway key — see autoRefreshHelpersIfStale's
+        // opts.pubkeyPemOverride doc comment for why that injection point
+        // exists at all).
         let trusted = null;
         try {
-            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'));
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'), opts.pubkeyPemOverride);
         }
         catch {
             trusted = null;
@@ -118,10 +169,19 @@ async function writeCriticalHelpers(helpersDir, version) {
     // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
     // OWN compiled generators (the trust root; no external file to verify).
     const gen = await import('./helpers-generator.js');
+    const statusGen = await import('./statusline-generator.js');
     const files = {
         'hook-handler.cjs': gen.generateHookHandler(),
         'intelligence.cjs': gen.generateIntelligenceStub(),
         'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+        // Fallback needs the same generator inputs `ruflo init` uses. We match the
+        // hardcoded default (maxAgents 15) because the fallback fires when the
+        // installed package is unresolvable — no way to read the user's project
+        // config from here. Fresh `ruflo init` still generates a per-project value.
+        'statusline.cjs': statusGen.generateStatuslineScript({
+            statusline: { enabled: true, style: 'compact' },
+            runtime: { maxAgents: 15 },
+        }),
     };
     let wrote = false;
     for (const [name, content] of Object.entries(files)) {
@@ -147,13 +207,35 @@ async function writeCriticalHelpers(helpersDir, version) {
  * stamp read + string compare (sub-ms); the copy runs at most once per version
  * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
  * existing hook-handler.cjs — never creates files in an unrelated directory).
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) against THIS project directory
+ * would see its own older version != the project's newer stamp and silently
+ * overwrite hand-fixed `hook-handler.cjs`/`intelligence.cjs` with its own
+ * older, already-superseded bundled copies. Comparing with `semver.gt`
+ * instead of `!==` makes that impossible: an older or equal installed
+ * version is always a no-op, regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
+ * THIS repo's actual current `.claude/helpers` + its real Ed25519 signature —
+ * fine for production (that coupling to the real source IS the point), but
+ * it means a test exercising that path for real would only pass when this
+ * repo's manifest happens to be currently re-signed, which is a separately-
+ * gated, occasionally-stale publish-time step. `sourceDirOverride` +
+ * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash →
+ * copy logic without depending on that.
  */
-export async function autoRefreshHelpersIfStale(cwd) {
+export async function autoRefreshHelpersIfStale(cwd, opts = {}) {
     try {
         const helpersDir = path.join(cwd, '.claude', 'helpers');
         if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
             return { refreshed: false };
-        const version = getInstalledCliVersion();
+        const version = opts.versionOverride ?? getInstalledCliVersion();
         let stamped = '';
         try {
             stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
@@ -161,7 +243,15 @@ export async function autoRefreshHelpersIfStale(cwd) {
         catch { /* pre-feature: unstamped */ }
         if (stamped === version)
             return { refreshed: false }; // up to date — fast path
-        const res = await writeCriticalHelpers(helpersDir, version);
+        if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
+            // Stamped version is already >= what this binary reports — refreshing
+            // would silently DOWNGRADE the project's helpers. Skip, untouched.
+            return { refreshed: false };
+        }
+        const res = await writeCriticalHelpers(helpersDir, version, {
+            sourceDirOverride: opts.sourceDirOverride,
+            pubkeyPemOverride: opts.pubkeyPemOverride,
+        });
         // A blocked refresh is a SECURITY signal (tampered source/manifest) — surface
         // it, don't advance the stamp, and leave the project's existing helpers intact.
         if (res.blocked)

package/dist/src/init/helpers-generator.js

@@ -448,6 +448,7 @@ export function generateHookHandler() {
         '',
         "const path = require('path');",
         "const fs = require('fs');",
+        "const os = require('os');",
         '',
         'const helpersDir = __dirname;',
         '',
@@ -537,6 +538,57 @@ export function generateHookHandler() {
         '    } else {',
         "      console.log('[INFO] Router not available, using default routing');",
         '    }',
+        '',
+        '    // Rate-limit -> sponsored-capacity nudge (ADR-312/313). Fires here,',
+        '    // client-side, BEFORE the API call this prompt would make - so it',
+        '    // still reaches the transcript even if that call then fails from the',
+        '    // rate limit. Cheap local file reads only; never a network call or a',
+        '    // child process, so it cannot add latency to prompt submission.',
+        '    try {',
+        "      var rlFunnelEnv = process.env.RUFLO_FUNNEL;",
+        '      var rlDisabledByEnv = rlFunnelEnv !== undefined && /^(0|false|off|no)$/i.test(String(rlFunnelEnv).trim());',
+        "      var rlCiVars = ['CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'TRAVIS', 'BUILDKITE', 'JENKINS_URL', 'TEAMCITY_VERSION', 'TF_BUILD'];",
+        '      var rlIsCi = rlCiVars.some(function (v) {',
+        '        var val = process.env[v];',
+        "        return val !== undefined && val !== '' && val !== '0' && String(val).toLowerCase() !== 'false';",
+        '      });',
+        "      var rlHome = path.join(os.homedir(), '.ruflo');",
+        '      var rlUserDisabled = false;',
+        '      try {',
+        "        var rlUserCfg = JSON.parse(fs.readFileSync(path.join(rlHome, 'funnel.json'), 'utf8'));",
+        '        rlUserDisabled = !!(rlUserCfg && rlUserCfg.enabled === false);',
+        '      } catch (e) { /* absent/malformed = not disabled */ }',
+        '      var rlProjectDisabled = false;',
+        '      try {',
+        "        var rlProjCfg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'claude-flow.config.json'), 'utf8'));",
+        '        rlProjectDisabled = !!(rlProjCfg && rlProjCfg.funnel && rlProjCfg.funnel.enabled === false);',
+        '      } catch (e) { /* absent/malformed = not disabled */ }',
+        '',
+        '      if (!rlDisabledByEnv && !rlIsCi && !rlUserDisabled && !rlProjectDisabled) {',
+        '        var rlStatus = null;',
+        "        try { rlStatus = JSON.parse(fs.readFileSync(path.join(rlHome, 'rate-limit-status.json'), 'utf8')); } catch (e) { /* not flagged */ }",
+        '        var rlIsLimited = false;',
+        '        if (rlStatus && rlStatus.limited) {',
+        '          if (rlStatus.since) {',
+        '            var rlSinceMs = Date.parse(rlStatus.since);',
+        '            rlIsLimited = isNaN(rlSinceMs) ? true : (Date.now() - rlSinceMs) < 6 * 60 * 60 * 1000;',
+        '          } else {',
+        '            rlIsLimited = true;',
+        '          }',
+        '        }',
+        '        if (rlIsLimited) {',
+        '          var rlConsented = false;',
+        '          try {',
+        "            var rlConsentFile = JSON.parse(fs.readFileSync(path.join(rlHome, 'consent.json'), 'utf8'));",
+        "            var rlReceipt = rlConsentFile && rlConsentFile['sponsored-downtime'];",
+        '            rlConsented = !!(rlReceipt && rlReceipt.granted === true && rlReceipt.at !== null && rlReceipt.policyVersion === 1);',
+        '          } catch (e) { /* not consented */ }',
+        '          if (!rlConsented) {',
+        "            console.log('[COGNITUM] Hit your Claude usage limit? Free sponsored capacity is available at cognitum.one/meta-llm -- run: ruflo proxy sponsor-enable --yes');",
+        '          }',
+        '        }',
+        '      }',
+        '    } catch (e) { /* nudge must never break the hook */ }',
         '  },',
         '',
         "  'pre-bash': () => {",

package/dist/src/init/mcp-generator.js

@@ -40,10 +40,15 @@ export function generateMCPConfig(options) {
     const npmEnv = {
         npm_config_update_notifier: 'false',
     };
-    // Ruflo MCP server (core) — uses ruflo wrapper for portable npm-resolved invocation.
-    // #2206: key MUST be 'claude-flow' so all plugins resolve as mcp__claude-flow__*.
-    // The command args (ruflo@latest mcp start) are the correct wrapper invocation — only the
-    // registration KEY changes here.
+    // Ruflo MCP server (core) — the registration KEY is intentionally
+    // `claude-flow` (not `ruflo`) because #2206 established that all ~166
+    // plugin tool references use `mcp__claude-flow__*`. The invoked binary
+    // is `ruflo@latest` (the post-rename wrapper) — only the registration
+    // name stays legacy so plugin tool resolution keeps working.
+    // #2612 (duplicate `claude-flow` + `ruflo` registrations after users
+    // followed pre-rename setup docs) is healed by `ruflo doctor`, which
+    // detects the duplicate and instructs the operator to remove the
+    // extra `ruflo`-keyed entry — NOT by flipping the canonical key here.
     if (config.claudeFlow) {
         mcpServers['claude-flow'] = createMCPServerEntry(['ruflo@latest', 'mcp', 'start'], {
             ...npmEnv,
@@ -79,7 +84,7 @@ export function generateMCPCommands(options) {
     const config = options.mcp;
     if (isWindows()) {
         if (config.claudeFlow) {
-            // #2206: registration name must be 'claude-flow' to match mcp__claude-flow__* tool naming
+            // #2206: registration name must be `claude-flow` to match mcp__claude-flow__* plugin tool references
             commands.push('claude mcp add claude-flow -- cmd /c npx -y ruflo@latest mcp start');
         }
         if (config.ruvSwarm) {
@@ -91,7 +96,7 @@ export function generateMCPCommands(options) {
     }
     else {
         if (config.claudeFlow) {
-            // #2206: registration name must be 'claude-flow' to match mcp__claude-flow__* tool naming
+            // #2206: registration name must be `claude-flow` to match mcp__claude-flow__* plugin tool references
             commands.push("claude mcp add claude-flow -- npx -y ruflo@latest mcp start");
         }
         if (config.ruvSwarm) {