claude-flow 3.25.5 → 3.26.0

package/v3/@claude-flow/cli/dist/src/funnel/precedence.js

@@ -0,0 +1,85 @@
+/**
+ * Control precedence resolver — ADR-305 (normative).
+ *
+ *   1. RUFLO_FUNNEL=0            (environment)
+ *   2. Enterprise managed policy
+ *   3. User config (funnel.enabled — user-level and project-level)
+ *   4. Package default
+ *   5. Remote signed policy      (only when the freshness feed is enabled)
+ *
+ * A lower-precedence source must never re-enable a higher-precedence
+ * disable — implemented as a strict AND chain: every source can veto,
+ * none can override a veto above it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readStateJson } from './state.js';
+import { getDisclosure } from './disclosure.js';
+function envDisabled(env) {
+    const v = env.RUFLO_FUNNEL;
+    return v !== undefined && /^(0|false|off|no)$/i.test(v.trim());
+}
+function enterprisePolicyDisabled(env) {
+    const candidates = [];
+    if (env.RUFLO_ENTERPRISE_POLICY)
+        candidates.push(env.RUFLO_ENTERPRISE_POLICY);
+    if (process.platform === 'win32') {
+        if (env.ProgramData)
+            candidates.push(path.join(env.ProgramData, 'ruflo', 'policy.json'));
+    }
+    else {
+        candidates.push('/etc/ruflo/policy.json');
+    }
+    for (const p of candidates) {
+        try {
+            const policy = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (policy?.funnel?.enabled === false)
+                return true;
+        }
+        catch {
+            // unreadable/absent policy is not a policy
+        }
+    }
+    return false;
+}
+function userConfigDisabled() {
+    const cfg = readStateJson('funnel.json');
+    return cfg?.enabled === false;
+}
+function projectConfigDisabled(cwd) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(cwd, 'claude-flow.config.json'), 'utf-8'));
+        return cfg?.funnel?.enabled === false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remote signed policy (ADR-305 freshness kill switch). The feed is opt-in
+ * and OFF by default; when a validated policy has been stored locally it can
+ * only disable — sitting at the bottom of the chain guarantees it can never
+ * re-enable anything a higher source turned off.
+ */
+function remotePolicyDisabled() {
+    const policy = readStateJson('funnel-remote-policy.json');
+    return policy?.funnelEnabled === false;
+}
+export function resolveFunnelEnabled(cwd = process.cwd(), env = process.env) {
+    if (envDisabled(env))
+        return { enabled: false, decidedBy: 'env' };
+    if (enterprisePolicyDisabled(env))
+        return { enabled: false, decidedBy: 'enterprise-policy' };
+    if (userConfigDisabled())
+        return { enabled: false, decidedBy: 'user-config' };
+    if (projectConfigDisabled(cwd))
+        return { enabled: false, decidedBy: 'project-config' };
+    // Declining the disclosure disables all funnel surfaces (ADR-301 invariant).
+    if (getDisclosure().state === 'disclosed_disabled') {
+        return { enabled: false, decidedBy: 'disclosure-declined' };
+    }
+    if (remotePolicyDisabled())
+        return { enabled: false, decidedBy: 'remote-policy' };
+    return { enabled: true, decidedBy: 'package-default' };
+}
+//# sourceMappingURL=precedence.js.map

package/v3/@claude-flow/cli/dist/src/funnel/promo.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Promo-row orchestrator — the single entry point the statusline hook calls
+ * (ADR-301). Applies, in order:
+ *
+ *   1. Control precedence (env / enterprise / user / project / remote) —
+ *      any disable → nothing renders, ever.
+ *   2. Environment gates — CI never sees funnel content.
+ *   3. Disclosure gate — an upgraded install shows the disclosure text
+ *      (with the disable instruction) before any message; promotional
+ *      content only after the grace window.
+ *   4. ADR-313 sponsored-downtime override — preempts everything below
+ *      while rate-limited (unconditional, not slot-based).
+ *   5. Local insight ticker (insights.ts) — a reserved 1-in-5 slot shows an
+ *      environment/task-aware suggestion (CVEs, uncommitted changes,
+ *      power-saver state) when one exists; otherwise falls through.
+ *   6. Rotation — 4:1 educational:promotional, 30-min promo repeat cap.
+ *
+ * Output is plain text (no ANSI — the renderer applies its own fixed
+ * style), ≤ 80 columns, already sanitized by the message pipeline.
+ */
+import type { PromoRow } from './types.js';
+import { type LocalInsightContext } from './insights.js';
+export interface PromoContext {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+    /**
+     * Whether the calling surface is an interactive session. The statusline
+     * hook is spawned with piped stdio by an interactive host, so the caller
+     * asserts interactivity; directly-run non-TTY invocations pass false.
+     */
+    interactive: boolean;
+    /**
+     * Local environment/task signal for the insight ticker (insights.ts) —
+     * optional and additive. Callers that don't pass it simply never see a
+     * local insight; the remote rotation is entirely unaffected either way.
+     */
+    localInsights?: LocalInsightContext;
+}
+export declare function getFunnelPromo(ctx: PromoContext): PromoRow | null;
+//# sourceMappingURL=promo.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/promo.js

@@ -0,0 +1,144 @@
+/**
+ * Promo-row orchestrator — the single entry point the statusline hook calls
+ * (ADR-301). Applies, in order:
+ *
+ *   1. Control precedence (env / enterprise / user / project / remote) —
+ *      any disable → nothing renders, ever.
+ *   2. Environment gates — CI never sees funnel content.
+ *   3. Disclosure gate — an upgraded install shows the disclosure text
+ *      (with the disable instruction) before any message; promotional
+ *      content only after the grace window.
+ *   4. ADR-313 sponsored-downtime override — preempts everything below
+ *      while rate-limited (unconditional, not slot-based).
+ *   5. Local insight ticker (insights.ts) — a reserved 1-in-5 slot shows an
+ *      environment/task-aware suggestion (CVEs, uncommitted changes,
+ *      power-saver state) when one exists; otherwise falls through.
+ *   6. Rotation — 4:1 educational:promotional, 30-min promo repeat cap.
+ *
+ * Output is plain text (no ANSI — the renderer applies its own fixed
+ * style), ≤ 80 columns, already sanitized by the message pipeline.
+ */
+import { resolveFunnelEnabled } from './precedence.js';
+import { isCI } from './environment.js';
+import { getDisclosure, promoEligible, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
+import { clickTrackedUrl } from './attribution.js';
+import { selectMessage, ROTATION_SLOT_MS } from './rotation.js';
+import { recordFunnelEvent } from './events.js';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+import { hasConsent } from './consent.js';
+import { readRateLimitStatus } from './rate-limit-notifier.js';
+import { selectLocalInsight } from './insights.js';
+/**
+ * ADR-313 priority override: when the user has manually flagged a Claude
+ * usage limit (ADR-312 Phase 0), preempt normal rotation with a dedicated
+ * CTA — same precedent as ADR-303's credit-exhaustion recovery surface.
+ * Two states depending on whether sponsored-downtime consent is granted:
+ *   - not yet enabled: an actionable CTA to enable it
+ *   - already enabled: a quiet status line confirming it's active
+ * Both message strings use the exact " · manage: " anchor the renderer
+ * already splits on (statusline-generator.ts getPromoRow) — no renderer
+ * change needed; the command portion renders bold, never as a fake link.
+ * Returns null when the rate-limit flag isn't set (no override).
+ */
+function getSponsoredDowntimeOverride(now) {
+    const status = readRateLimitStatus(now);
+    if (!status.limited)
+        return null;
+    if (hasConsent('sponsored-downtime')) {
+        return {
+            text: '⚡ Running on sponsored Cognitum capacity · manage: ruflo proxy sponsor-disable',
+            kind: 'promotional',
+        };
+    }
+    return {
+        text: '⚡ Free Cognitum capacity while you wait · manage: ruflo proxy sponsor-enable',
+        kind: 'promotional',
+    };
+}
+/** 1 in 5 slots, a different phase than rotation.ts's promo slot (slot%5==4)
+ * so the two never collide — reserved for a local insight IF one exists;
+ * otherwise falls through to the normal remote rotation untouched. This is
+ * the "ticker" cadence: insights appear periodically, never permanently
+ * take over the row, and never appear at all when nothing is actionable. */
+const INSIGHT_SLOT_MODULO = 5;
+const INSIGHT_SLOT_PHASE = 2;
+function isInsightSlot(now) {
+    const slot = Math.floor(now.getTime() / ROTATION_SLOT_MS);
+    return slot % INSIGHT_SLOT_MODULO === INSIGHT_SLOT_PHASE;
+}
+export function getFunnelPromo(ctx) {
+    const env = ctx.env ?? process.env;
+    const now = ctx.now ?? new Date();
+    if (!ctx.interactive)
+        return null;
+    if (isCI(env))
+        return null;
+    const decision = resolveFunnelEnabled(ctx.cwd ?? process.cwd(), env);
+    if (!decision.enabled)
+        return null;
+    const release = getInstalledCliVersion();
+    // Disclosure gate: never a message before the disclosure has been shown
+    // and its grace window has passed. The disclosure MESSAGE itself is now
+    // remote-sourced (ADR-311) — selectDisclosureMessage() returns null when
+    // the remote pool hasn't populated yet (cold start / outage), and per the
+    // "zero local promo content" design, null means show nothing this cycle.
+    const disclosure = getDisclosure();
+    if (disclosure.state === 'never_seen') {
+        const msg = selectDisclosureMessage(now);
+        if (!msg)
+            return null; // fail-closed: no remote disclosure cached yet
+        recordDisclosureShown(now);
+        recordFunnelEvent('disclosure_shown', 'statusline', release, { now, messageId: msg.id });
+        const url = msg.url ? clickTrackedUrl(msg.id, msg.url, {
+            medium: 'statusline', campaign: 'disclosure', content: msg.id, now,
+        }) : undefined;
+        return { text: msg.text, kind: 'disclosure', url };
+    }
+    if (!promoEligible(now)) {
+        if (disclosure.state === 'disclosed_enabled') {
+            const msg = selectDisclosureMessage(now);
+            if (!msg)
+                return null; // fail-closed
+            const url = msg.url ? clickTrackedUrl(msg.id, msg.url, {
+                medium: 'statusline', campaign: 'disclosure', content: msg.id, now,
+            }) : undefined;
+            return { text: msg.text, kind: 'disclosure', url };
+        }
+        return null; // disclosed_disabled is caught by precedence, but stay fail-closed
+    }
+    // ADR-313 priority override: a self-reported usage-limit flag preempts
+    // normal rotation, exactly the way ADR-303's credit-exhaustion recovery
+    // is designed to preempt it. Only reachable here — i.e. only after the
+    // disclosure invariant (ADR-301 "no promotional content before
+    // disclosure") has already been satisfied above.
+    const override = getSponsoredDowntimeOverride(now);
+    if (override)
+        return override;
+    // Local insight ticker: on its reserved 1-in-5 slot, show the highest-
+    // priority environment/task insight if one exists — CVEs pending,
+    // uncommitted changes, power-saver active, etc. (insights.ts). No
+    // insight this render (or no context passed) → fall straight through to
+    // the untouched remote rotation below, same as any other slot.
+    if (ctx.localInsights && isInsightSlot(now)) {
+        const insight = selectLocalInsight(ctx.localInsights);
+        if (insight)
+            return { text: insight.text, kind: 'insight' };
+    }
+    const msg = selectMessage(now, release);
+    if (!msg)
+        return null;
+    // Any message carrying a URL (educational tips included) routes through
+    // the server click-redirect so `promo_open` + coarse geo are captured
+    // before 302ing to the real target — click counting is uniform across
+    // the whole rotation, not just the promotional slot. If the click
+    // endpoint chain rejects the URL for any reason, fall back to the
+    // UTM-decorated direct link so the click still lands where it should.
+    let url;
+    if (msg.url) {
+        url = clickTrackedUrl(msg.id, msg.url, {
+            medium: 'statusline', campaign: msg.class, content: msg.id, now,
+        });
+    }
+    return { text: msg.text, kind: msg.class, url };
+}
+//# sourceMappingURL=promo.js.map

package/v3/@claude-flow/cli/dist/src/funnel/rate-limit-notifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rate-limit notifier — ADR-312 Phase 0 out-of-band signal path.
+ *
+ * Structural mirror of credit-notifier.ts. This is NOT automatic detection
+ * — ADR-312 established that Claude Code does not currently expose any way
+ * to detect its own usage-limit state from outside its process (verified
+ * against the actual installed CLI source, not assumed). This module is the
+ * MANUAL, self-reported alternative: the user tells ruflo they've hit a
+ * limit, ruflo remembers it, and the funnel promo row can react.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/rate-limit-status.json = { limited: bool, since: ISO, cleared: ISO|null }
+ *
+ * A TTL (default 6h) auto-expires a forgotten flag so a stale manual mark
+ * doesn't linger indefinitely if the user forgets to clear it — Claude
+ * usage limits reset on hours-to-days cadences (five_hour / seven_day per
+ * ADR-312's grounded research), so 6h is a reasonable "the user probably
+ * forgot to clear this" bound without requiring per-type precision we
+ * don't have.
+ */
+export declare const RATE_LIMIT_STATUS_FILE = "rate-limit-status.json";
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export declare const RATE_LIMIT_TTL_MS: number;
+export interface RateLimitStatus {
+    limited: boolean;
+    since: string | null;
+    cleared: string | null;
+    /** ADR-314 §D1 — last time `limited` actually changed value; gates the toggle cooldown. */
+    lastToggleAt: string | null;
+}
+/** Read the current rate-limit status. Never throws. Applies the TTL. */
+export declare function readRateLimitStatus(now?: Date): RateLimitStatus;
+/**
+ * Mark as rate-limited — idempotent. Sets `since` on the first mark, leaves
+ * it alone on subsequent marks so the user sees a stable "since" timestamp
+ * until they clear it or the TTL expires. Refuses to flip false→true inside
+ * the ADR-314 §D1 cooldown window (returns false; a no-op re-mark of an
+ * already-true flag is unaffected — that's not a state change).
+ */
+export declare function markRateLimited(now?: Date): boolean;
+/**
+ * Clear rate-limited status. Called via `ruflo settings notices
+ * rate-limited --clear`, automatically by the TTL, or once a real Phase 1/2
+ * signal (ADR-312) confirms the limit has reset. Refuses to flip true→false
+ * inside the cooldown window (returns false); clearing an already-clear
+ * flag is always allowed (not a state change, and TTL auto-clear must never
+ * be blocked by a cooldown it didn't itself trigger).
+ */
+export declare function clearRateLimitStatus(now?: Date): boolean;
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when not rate-limited (no surface).
+ */
+export declare function rateLimitNotice(now?: Date): string | null;
+//# sourceMappingURL=rate-limit-notifier.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/rate-limit-notifier.js

@@ -0,0 +1,102 @@
+/**
+ * Rate-limit notifier — ADR-312 Phase 0 out-of-band signal path.
+ *
+ * Structural mirror of credit-notifier.ts. This is NOT automatic detection
+ * — ADR-312 established that Claude Code does not currently expose any way
+ * to detect its own usage-limit state from outside its process (verified
+ * against the actual installed CLI source, not assumed). This module is the
+ * MANUAL, self-reported alternative: the user tells ruflo they've hit a
+ * limit, ruflo remembers it, and the funnel promo row can react.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/rate-limit-status.json = { limited: bool, since: ISO, cleared: ISO|null }
+ *
+ * A TTL (default 6h) auto-expires a forgotten flag so a stale manual mark
+ * doesn't linger indefinitely if the user forgets to clear it — Claude
+ * usage limits reset on hours-to-days cadences (five_hour / seven_day per
+ * ADR-312's grounded research), so 6h is a reasonable "the user probably
+ * forgot to clear this" bound without requiring per-type precision we
+ * don't have.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { cooldownActive } from './toggle-cooldown.js';
+export const RATE_LIMIT_STATUS_FILE = 'rate-limit-status.json';
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export const RATE_LIMIT_TTL_MS = 6 * 60 * 60 * 1000;
+/** Read the current rate-limit status. Never throws. Applies the TTL. */
+export function readRateLimitStatus(now = new Date()) {
+    const raw = readStateJson(RATE_LIMIT_STATUS_FILE);
+    const status = {
+        limited: raw?.limited ?? false,
+        since: raw?.since ?? null,
+        cleared: raw?.cleared ?? null,
+        lastToggleAt: raw?.lastToggleAt ?? null,
+    };
+    if (status.limited && status.since) {
+        const since = Date.parse(status.since);
+        if (!Number.isNaN(since) && now.getTime() - since >= RATE_LIMIT_TTL_MS) {
+            return { limited: false, since: status.since, cleared: now.toISOString(), lastToggleAt: status.lastToggleAt };
+        }
+    }
+    return status;
+}
+/**
+ * Mark as rate-limited — idempotent. Sets `since` on the first mark, leaves
+ * it alone on subsequent marks so the user sees a stable "since" timestamp
+ * until they clear it or the TTL expires. Refuses to flip false→true inside
+ * the ADR-314 §D1 cooldown window (returns false; a no-op re-mark of an
+ * already-true flag is unaffected — that's not a state change).
+ */
+export function markRateLimited(now = new Date()) {
+    const current = readRateLimitStatus(now);
+    if (current.limited && current.since)
+        return true; // already flagged, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(RATE_LIMIT_STATUS_FILE, {
+        limited: true,
+        since: current.since ?? now.toISOString(),
+        cleared: null,
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * Clear rate-limited status. Called via `ruflo settings notices
+ * rate-limited --clear`, automatically by the TTL, or once a real Phase 1/2
+ * signal (ADR-312) confirms the limit has reset. Refuses to flip true→false
+ * inside the cooldown window (returns false); clearing an already-clear
+ * flag is always allowed (not a state change, and TTL auto-clear must never
+ * be blocked by a cooldown it didn't itself trigger).
+ */
+export function clearRateLimitStatus(now = new Date()) {
+    const current = readRateLimitStatus(now);
+    if (!current.limited)
+        return true; // already clear, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(RATE_LIMIT_STATUS_FILE, {
+        limited: false,
+        since: current.since,
+        cleared: now.toISOString(),
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when not rate-limited (no surface).
+ */
+export function rateLimitNotice(now = new Date()) {
+    const status = readRateLimitStatus(now);
+    if (!status.limited)
+        return null;
+    const since = status.since ? Date.parse(status.since) : NaN;
+    if (Number.isNaN(since)) {
+        return 'Claude usage limit flagged · run: ruflo proxy sponsor-enable';
+    }
+    const ageMin = Math.max(0, Math.round((now.getTime() - since) / (60 * 1000)));
+    const when = ageMin < 1 ? 'just now' : ageMin < 60 ? `${ageMin}m ago` : `${Math.round(ageMin / 60)}h ago`;
+    return `Claude usage limit flagged (${when}) · run: ruflo proxy sponsor-enable`;
+}
+//# sourceMappingURL=rate-limit-notifier.js.map

package/v3/@claude-flow/cli/dist/src/funnel/rotation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rotation scheduler — ADR-301 content ratio, enforced structurally.
+ *
+ *   - Educational: at least 4 of every 5 rotation slots.
+ *   - Promotional: at most 1 of every 5 slots (slot % 5 === 4), and only
+ *     when no promotion has shown in the last 30 minutes.
+ *   - Deterministic: selection is a pure function of (time slot, registry,
+ *     last-promo state) — no Math.random, so renders are reproducible and
+ *     the statusline cache can't skew the ratio.
+ */
+import type { FunnelMessage } from './types.js';
+/** One rotation slot — ADR-301 allows 15–30s; 20s sits inside the band. */
+export declare const ROTATION_SLOT_MS = 20000;
+/** The same promotion appears at most once every 30 minutes (ADR-301). */
+export declare const PROMO_REPEAT_CAP_MS: number;
+/** 1 promotional slot per 5 (ADR-301: ≤ 1 in 5 rotations). */
+export declare const PROMO_SLOT_MODULO = 5;
+export declare function selectMessage(now?: Date, release?: string): FunnelMessage | null;
+//# sourceMappingURL=rotation.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/rotation.js

@@ -0,0 +1,70 @@
+/**
+ * Rotation scheduler — ADR-301 content ratio, enforced structurally.
+ *
+ *   - Educational: at least 4 of every 5 rotation slots.
+ *   - Promotional: at most 1 of every 5 slots (slot % 5 === 4), and only
+ *     when no promotion has shown in the last 30 minutes.
+ *   - Deterministic: selection is a pure function of (time slot, registry,
+ *     last-promo state) — no Math.random, so renders are reproducible and
+ *     the statusline cache can't skew the ratio.
+ */
+import { MESSAGES, eligibleMessagesFromPools } from './messages.js';
+import { getRemoteMessages, refreshRemoteMessages } from './message-transport.js';
+import { readStateJson, writeStateJson } from './state.js';
+import { recordFunnelEvent } from './events.js';
+const ROTATION_FILE = 'funnel-rotation.json';
+/** One rotation slot — ADR-301 allows 15–30s; 20s sits inside the band. */
+export const ROTATION_SLOT_MS = 20_000;
+/** The same promotion appears at most once every 30 minutes (ADR-301). */
+export const PROMO_REPEAT_CAP_MS = 30 * 60 * 1000;
+/** 1 promotional slot per 5 (ADR-301: ≤ 1 in 5 rotations). */
+export const PROMO_SLOT_MODULO = 5;
+export function selectMessage(now = new Date(), release = 'unknown') {
+    // Kick a background refresh — never awaited, never blocks render. The
+    // remote pool becomes visible on subsequent selects once cached.
+    void refreshRemoteMessages();
+    // Merge: remote pool authoritative, in-code pool fallback (by id).
+    const pool = eligibleMessagesFromPools(MESSAGES, getRemoteMessages(), now);
+    const educational = pool.filter((m) => m.class === 'educational');
+    const promotional = pool.filter((m) => m.class === 'promotional');
+    if (educational.length === 0 && promotional.length === 0)
+        return null;
+    const slot = Math.floor(now.getTime() / ROTATION_SLOT_MS);
+    const promoSlot = slot % PROMO_SLOT_MODULO === PROMO_SLOT_MODULO - 1;
+    let selected = null;
+    if (promoSlot && promotional.length > 0 && promoCapClear(now)) {
+        selected = promotional[Math.floor(slot / PROMO_SLOT_MODULO) % promotional.length];
+        recordPromoShown(selected, now);
+    }
+    else if (educational.length > 0) {
+        selected = educational[slot % educational.length];
+    }
+    // Fire an impression event for whichever message was selected. Consent-gated
+    // (recordFunnelEvent no-ops without telemetry consent). Idempotency across
+    // renders in the same slot is handled by the same-slot deduplication in
+    // the events transport — we don't try to dedupe here because the slot
+    // math already returns the same id for the same slot, giving downstream
+    // aggregation a per-slot boolean.
+    if (selected) {
+        recordFunnelEvent('promo_impression', 'statusline', release, {
+            now, messageId: selected.id,
+        });
+    }
+    return selected;
+}
+function promoCapClear(now) {
+    const state = readStateJson(ROTATION_FILE);
+    if (!state?.lastPromoAt)
+        return true;
+    const last = Date.parse(state.lastPromoAt);
+    if (Number.isNaN(last))
+        return true;
+    return now.getTime() - last >= PROMO_REPEAT_CAP_MS;
+}
+function recordPromoShown(msg, now) {
+    writeStateJson(ROTATION_FILE, {
+        lastPromoAt: now.toISOString(),
+        lastPromoId: msg.id,
+    });
+}
+//# sourceMappingURL=rotation.js.map

package/v3/@claude-flow/cli/dist/src/funnel/state.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Funnel state storage — user-level JSON files under ~/.ruflo (ADR-302/305).
+ *
+ * User-level (not project-level) so dismissals, consent, and disclosure
+ * persist across projects. Files are written 0600 and never committed.
+ * RUFLO_STATE_DIR overrides the directory (tests, unusual $HOME setups).
+ */
+export declare function funnelStateDir(): string;
+export declare function statePath(name: string): string;
+export declare function readStateJson<T>(name: string): T | null;
+export declare function writeStateJson(name: string, value: unknown): boolean;
+export declare function deleteStateFile(name: string): void;
+//# sourceMappingURL=state.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/state.js

@@ -0,0 +1,52 @@
+/**
+ * Funnel state storage — user-level JSON files under ~/.ruflo (ADR-302/305).
+ *
+ * User-level (not project-level) so dismissals, consent, and disclosure
+ * persist across projects. Files are written 0600 and never committed.
+ * RUFLO_STATE_DIR overrides the directory (tests, unusual $HOME setups).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export function funnelStateDir() {
+    const override = process.env.RUFLO_STATE_DIR;
+    if (override && override.trim())
+        return override;
+    return path.join(os.homedir(), '.ruflo');
+}
+export function statePath(name) {
+    return path.join(funnelStateDir(), name);
+}
+export function readStateJson(name) {
+    try {
+        const raw = fs.readFileSync(statePath(name), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStateJson(name, value) {
+    try {
+        const dir = funnelStateDir();
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const target = statePath(name);
+        // Write-then-rename so a crash never leaves a truncated state file.
+        const tmp = `${target}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(value, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        fs.renameSync(tmp, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function deleteStateFile(name) {
+    try {
+        fs.unlinkSync(statePath(name));
+    }
+    catch {
+        // already absent — fine
+    }
+}
+//# sourceMappingURL=state.js.map

package/v3/@claude-flow/cli/dist/src/funnel/toggle-cooldown.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared toggle cooldown — ADR-314 §D1.
+ *
+ * Self-reported flags (rate-limited, quota-low) have zero server-side
+ * verification (ADR-312's Phase 0 constraint carries over unchanged). A
+ * cooldown on how often the flag can actually CHANGE state is cheap,
+ * purely client-side friction against casual "always on" gaming or a
+ * scripted flip-flop loop — it does not stop a determined abuser (that
+ * needs the per-identity server-side quota ADR-314 flags as the real fix),
+ * but it raises the bar above "one line in a shell script."
+ */
+export declare const TOGGLE_COOLDOWN_MS: number;
+/** True when `lastToggleAt` is within the cooldown window of `now`. */
+export declare function cooldownActive(lastToggleAt: string | null, now: Date): boolean;
+/** Minutes remaining in the cooldown window — for user-facing messages. */
+export declare function cooldownRemainingMin(lastToggleAt: string | null, now: Date): number;
+//# sourceMappingURL=toggle-cooldown.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/toggle-cooldown.js

@@ -0,0 +1,32 @@
+/**
+ * Shared toggle cooldown — ADR-314 §D1.
+ *
+ * Self-reported flags (rate-limited, quota-low) have zero server-side
+ * verification (ADR-312's Phase 0 constraint carries over unchanged). A
+ * cooldown on how often the flag can actually CHANGE state is cheap,
+ * purely client-side friction against casual "always on" gaming or a
+ * scripted flip-flop loop — it does not stop a determined abuser (that
+ * needs the per-identity server-side quota ADR-314 flags as the real fix),
+ * but it raises the bar above "one line in a shell script."
+ */
+export const TOGGLE_COOLDOWN_MS = 10 * 60 * 1000;
+/** True when `lastToggleAt` is within the cooldown window of `now`. */
+export function cooldownActive(lastToggleAt, now) {
+    if (!lastToggleAt)
+        return false;
+    const t = Date.parse(lastToggleAt);
+    if (Number.isNaN(t))
+        return false;
+    return now.getTime() - t < TOGGLE_COOLDOWN_MS;
+}
+/** Minutes remaining in the cooldown window — for user-facing messages. */
+export function cooldownRemainingMin(lastToggleAt, now) {
+    if (!lastToggleAt)
+        return 0;
+    const t = Date.parse(lastToggleAt);
+    if (Number.isNaN(t))
+        return 0;
+    const remainingMs = TOGGLE_COOLDOWN_MS - (now.getTime() - t);
+    return Math.max(0, Math.ceil(remainingMs / (60 * 1000)));
+}
+//# sourceMappingURL=toggle-cooldown.js.map