claude-flow 3.25.6 → 3.26.0

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

@@ -0,0 +1,149 @@
+/**
+ * Remote message transport — best-effort fetch of the ADR-311 message
+ * feed, cached locally, validated through the ADR-301 content pipeline
+ * BEFORE any message is displayed.
+ *
+ * Design discipline:
+ *   1. **Never blocks the render.** The statusline reads only the local
+ *      cache. This module refreshes the cache in the background; a fresh
+ *      install shows the in-code fallback pool until the first refresh
+ *      lands (usually seconds after CLI startup).
+ *   2. **Content pipeline stays authoritative.** Every message the server
+ *      returns is validated by `isValidMessage()` from `messages.ts` —
+ *      same schema, same host allowlist, same control-char strip, same
+ *      80-column cap. A tampered or accidentally-broken remote feed can
+ *      pollute nothing.
+ *   3. **Fail silent.** Any network/parse/validation failure leaves the
+ *      previously-cached (or in-code) pool intact.
+ *   4. **Bounded cache size.** ≤ 128 KiB and ≤ 200 messages — matches
+ *      ADR-309's bounded-local-queue discipline.
+ *   5. **Kill switch.** `RUFLO_FUNNEL_MESSAGES=0` (or `RUFLO_FUNNEL=0`)
+ *      disables the fetcher entirely.
+ *   6. **Signature-verification hook.** Reserved for a future ADR-311
+ *      amendment; currently the transport-layer TLS + host allowlist is
+ *      the trust boundary. All content is treated as untrusted regardless.
+ */
+import * as https from 'https';
+import { URL as NodeUrl } from 'url';
+import { isValidMessage } from './messages.js';
+import { readStateJson, writeStateJson } from './state.js';
+const CACHE_FILE = 'funnel-messages-cache.json';
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h — matches server Cache-Control
+const CACHE_MAX_BYTES = 128 * 1024;
+const CACHE_MAX_MESSAGES = 200;
+const FETCH_TIMEOUT_MS = 4_000;
+/** Endpoint the client hits — overridable for staging / self-hosted. */
+export const DEFAULT_MESSAGES_ENDPOINT = process.env.RUFLO_FUNNEL_MESSAGES_ENDPOINT ?? 'https://funnel.ruv.io/v1/messages';
+function readCache() {
+    const raw = readStateJson(CACHE_FILE);
+    if (!raw || !Array.isArray(raw.messages))
+        return { fresh: false, messages: [] };
+    const age = Date.now() - (raw._ts ?? 0);
+    return { fresh: age < CACHE_TTL_MS, messages: raw.messages };
+}
+function writeCache(messages) {
+    // Bound the cache before persisting — messages come from an untrusted
+    // source, so we cap size regardless of server behavior.
+    let trimmed = messages.slice(0, CACHE_MAX_MESSAGES);
+    let body = JSON.stringify({ _ts: Date.now(), messages: trimmed });
+    while (Buffer.byteLength(body, 'utf-8') > CACHE_MAX_BYTES && trimmed.length > 0) {
+        trimmed = trimmed.slice(0, trimmed.length - 1);
+        body = JSON.stringify({ _ts: Date.now(), messages: trimmed });
+    }
+    writeStateJson(CACHE_FILE, { _ts: Date.now(), messages: trimmed });
+}
+function httpsGet(url) {
+    return new Promise((resolve) => {
+        let target;
+        try {
+            target = new NodeUrl(url);
+        }
+        catch {
+            resolve({ status: 0, body: 'bad-url' });
+            return;
+        }
+        if (target.protocol !== 'https:') {
+            resolve({ status: 0, body: 'non-https' });
+            return;
+        }
+        const req = https.request({
+            hostname: target.hostname,
+            port: target.port || 443,
+            path: target.pathname + target.search,
+            method: 'GET',
+            headers: {
+                'User-Agent': 'ruflo-funnel/messages',
+                'Accept': 'application/json',
+            },
+        }, (res) => {
+            let chunks = '';
+            res.setEncoding('utf-8');
+            res.on('data', (chunk) => { chunks += chunk; });
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, body: chunks }));
+        });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve({ status: 0, body: 'timeout' });
+        });
+        req.on('error', () => resolve({ status: 0, body: 'error' }));
+        req.end();
+    });
+}
+function killSwitched(env = process.env) {
+    const kill = (v) => v !== undefined && /^(0|false|off|no)$/i.test(v.trim());
+    return kill(env.RUFLO_FUNNEL_MESSAGES) || kill(env.RUFLO_FUNNEL);
+}
+/**
+ * Best-effort refresh of the cache. Safe to call at any point in the
+ * CLI lifecycle — returns a summary; never throws; never blocks longer
+ * than FETCH_TIMEOUT_MS + write time.
+ */
+export async function refreshRemoteMessages(opts) {
+    const env = opts?.env ?? process.env;
+    if (killSwitched(env))
+        return { refreshed: false, skipped: 'kill-switch' };
+    const cache = readCache();
+    if (!opts?.force && cache.fresh)
+        return { refreshed: false, skipped: 'fresh-cache' };
+    const endpoint = opts?.endpoint ?? DEFAULT_MESSAGES_ENDPOINT;
+    const res = await httpsGet(endpoint);
+    if (res.status !== 200)
+        return { refreshed: false, skipped: `http-${res.status}`, status: res.status };
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        return { refreshed: false, skipped: 'json-parse-error' };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return { refreshed: false, skipped: 'not-object' };
+    const raw = parsed.messages;
+    if (!Array.isArray(raw))
+        return { refreshed: false, skipped: 'no-messages-field' };
+    // Every message goes through the SAME pipeline the in-code pool uses.
+    // This is where trust boundary enforcement actually lives.
+    const now = new Date();
+    const accepted = [];
+    let rejected = 0;
+    for (const candidate of raw) {
+        if (isValidMessage(candidate, now)) {
+            accepted.push(candidate);
+        }
+        else {
+            rejected += 1;
+        }
+    }
+    writeCache(accepted);
+    return { refreshed: true, accepted: accepted.length, rejected, status: res.status };
+}
+/**
+ * Read the cached remote pool. Returns [] when the cache is empty or
+ * stale enough to distrust — callers should merge with the in-code
+ * fallback pool.
+ */
+export function getRemoteMessages() {
+    const cache = readCache();
+    return cache.messages;
+}
+//# sourceMappingURL=message-transport.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * Funnel message registry and content pipeline — ADR-301 signed content
+ * boundaries.
+ *
+ * Messages are inert data. Regardless of how a message reached this process
+ * (in-package today; the signed helper channel later), the renderer treats
+ * it as untrusted and enforces, before display:
+ *   - schema validation (invalid → dropped, never repaired)
+ *   - length bound (≤ 80 display columns → over-length dropped)
+ *   - URL host allowlist (exact hosts, in code — lookalikes/IPs dropped)
+ *   - expiry
+ *   - zero terminal control sequences (any control char, ANSI/OSC/DCS
+ *     escape, or bidi override → dropped, not stripped-and-shown)
+ *
+ * There is no eval path and no styling in the payload: color comes only
+ * from the renderer's own fixed styles.
+ */
+import type { FunnelMessage } from './types.js';
+export declare const MAX_MESSAGE_COLUMNS = 80;
+export declare function containsForbiddenSequences(text: string): boolean;
+/** Approximate terminal display width: wide CJK/emoji count 2. */
+export declare function displayWidth(text: string): number;
+export declare function isAllowedUrl(url: string): boolean;
+/**
+ * Full validation gate. Returns true only when every ADR-301 content
+ * boundary passes. Failures are silent drops by design — a bad message
+ * must never produce a visible error in the statusline.
+ */
+export declare function isValidMessage(msg: unknown, now?: Date): msg is FunnelMessage;
+/**
+ * Local promo/message content: INTENTIONALLY EMPTY (ADR-311 amendment).
+ *
+ * All rotation content (educational tips, promotional messages, and the
+ * disclosure notice) is served exclusively from the remote message feed
+ * (GET /v1/messages -> message-transport.ts -> Firestore). Zero message
+ * text or URLs ship in the CLI package.
+ *
+ * Fail-closed by design: if the remote feed is unreachable (network down,
+ * cert issue, server outage) and no prior successful fetch has populated
+ * the local cache, the rotation has nothing to show and the promo row
+ * simply does not render that cycle. There is no local content to fall
+ * back to -- this is a deliberate choice, not an oversight.
+ */
+export declare const MESSAGES: FunnelMessage[];
+/** Messages that survive every content boundary right now. */
+export declare function eligibleMessages(now?: Date): FunnelMessage[];
+/**
+ * Merge the remote (cached) message pool with the in-code fallback pool.
+ * The remote pool is authoritative when populated; the in-code pool
+ * covers cold starts and API-down periods. Deduplication is by `id` —
+ * remote wins over in-code for a given id so admins can override without
+ * a client release.
+ */
+export declare function eligibleMessagesFromPools(inCodePool: readonly FunnelMessage[], remotePool: readonly FunnelMessage[], now?: Date): FunnelMessage[];
+//# sourceMappingURL=messages.d.ts.map

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

@@ -0,0 +1,160 @@
+/**
+ * Funnel message registry and content pipeline — ADR-301 signed content
+ * boundaries.
+ *
+ * Messages are inert data. Regardless of how a message reached this process
+ * (in-package today; the signed helper channel later), the renderer treats
+ * it as untrusted and enforces, before display:
+ *   - schema validation (invalid → dropped, never repaired)
+ *   - length bound (≤ 80 display columns → over-length dropped)
+ *   - URL host allowlist (exact hosts, in code — lookalikes/IPs dropped)
+ *   - expiry
+ *   - zero terminal control sequences (any control char, ANSI/OSC/DCS
+ *     escape, or bidi override → dropped, not stripped-and-shown)
+ *
+ * There is no eval path and no styling in the payload: color comes only
+ * from the renderer's own fixed styles.
+ */
+export const MAX_MESSAGE_COLUMNS = 80;
+/**
+ * Exact-host allowlist (ADR-301). Ships in code, never in the payload.
+ * github.com is allowed only under /ruvnet/.
+ */
+const ALLOWED_URL_HOSTS = new Set([
+    'cognitum.one', 'www.cognitum.one', 'docs.cognitum.one',
+    // agentics.org — the rUv-authored OSS foundation. Distinct sponsor from
+    // cognitum.one; carries its own promotional messages in the rotation.
+    'agentics.org', 'www.agentics.org',
+]);
+const GITHUB_HOST = 'github.com';
+const GITHUB_PATH_PREFIX = '/ruvnet/';
+/**
+ * C0/C1 controls (incl. ESC, so every ANSI/OSC/DCS sequence trips this),
+ * DEL, and Unicode bidirectional overrides/isolates.
+ */
+// eslint-disable-next-line no-control-regex
+const FORBIDDEN_CHARS = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+export function containsForbiddenSequences(text) {
+    return FORBIDDEN_CHARS.test(text);
+}
+/** Approximate terminal display width: wide CJK/emoji count 2. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (cp === 0xfe0f || cp === 0x200d)
+            continue; // variation selector / ZWJ
+        const wide = (cp >= 0x1100 && cp <= 0x115f) ||
+            (cp >= 0x2e80 && cp <= 0xa4cf) ||
+            (cp >= 0xac00 && cp <= 0xd7a3) ||
+            (cp >= 0xf900 && cp <= 0xfaff) ||
+            (cp >= 0xff00 && cp <= 0xff60) ||
+            (cp >= 0x1f000 && cp <= 0x1faff) ||
+            (cp >= 0x20000 && cp <= 0x3fffd);
+        width += wide ? 2 : 1;
+    }
+    return width;
+}
+export function isAllowedUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'https:')
+        return false;
+    if (ALLOWED_URL_HOSTS.has(parsed.hostname))
+        return true;
+    if (parsed.hostname === GITHUB_HOST && parsed.pathname.startsWith(GITHUB_PATH_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * Full validation gate. Returns true only when every ADR-301 content
+ * boundary passes. Failures are silent drops by design — a bad message
+ * must never produce a visible error in the statusline.
+ */
+export function isValidMessage(msg, now = new Date()) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const m = msg;
+    if (m.schemaVersion !== 1)
+        return false;
+    if (typeof m.id !== 'string' || m.id.length === 0 || m.id.length > 64)
+        return false;
+    if (m.class !== 'educational' && m.class !== 'promotional' && m.class !== 'disclosure')
+        return false;
+    if (typeof m.text !== 'string' || m.text.length === 0)
+        return false;
+    if (containsForbiddenSequences(m.text))
+        return false;
+    if (displayWidth(m.text) > MAX_MESSAGE_COLUMNS)
+        return false;
+    // Disclosure messages MUST carry the exact ADR-301 manage-instruction tail
+    // — losing that on a truncated/malformed remote message is an invariant
+    // violation, not a cosmetic issue. Never repaired; dropped instead.
+    if (m.class === 'disclosure' && !m.text.includes(' · manage: ruflo settings'))
+        return false;
+    if (m.url !== undefined) {
+        if (typeof m.url !== 'string' || !isAllowedUrl(m.url))
+            return false;
+    }
+    if (m.expiresAt !== undefined) {
+        if (typeof m.expiresAt !== 'string')
+            return false;
+        const exp = Date.parse(m.expiresAt);
+        if (Number.isNaN(exp) || exp <= now.getTime())
+            return false;
+    }
+    return true;
+}
+/**
+ * Local promo/message content: INTENTIONALLY EMPTY (ADR-311 amendment).
+ *
+ * All rotation content (educational tips, promotional messages, and the
+ * disclosure notice) is served exclusively from the remote message feed
+ * (GET /v1/messages -> message-transport.ts -> Firestore). Zero message
+ * text or URLs ship in the CLI package.
+ *
+ * Fail-closed by design: if the remote feed is unreachable (network down,
+ * cert issue, server outage) and no prior successful fetch has populated
+ * the local cache, the rotation has nothing to show and the promo row
+ * simply does not render that cycle. There is no local content to fall
+ * back to -- this is a deliberate choice, not an oversight.
+ */
+export const MESSAGES = [];
+/** Messages that survive every content boundary right now. */
+export function eligibleMessages(now = new Date()) {
+    return MESSAGES.filter((m) => isValidMessage(m, now));
+}
+/**
+ * Merge the remote (cached) message pool with the in-code fallback pool.
+ * The remote pool is authoritative when populated; the in-code pool
+ * covers cold starts and API-down periods. Deduplication is by `id` —
+ * remote wins over in-code for a given id so admins can override without
+ * a client release.
+ */
+export function eligibleMessagesFromPools(inCodePool, remotePool, now = new Date()) {
+    const seen = new Set();
+    const out = [];
+    for (const m of remotePool) {
+        if (!isValidMessage(m, now))
+            continue;
+        if (seen.has(m.id))
+            continue;
+        seen.add(m.id);
+        out.push(m);
+    }
+    for (const m of inCodePool) {
+        if (!isValidMessage(m, now))
+            continue;
+        if (seen.has(m.id))
+            continue;
+        seen.add(m.id);
+        out.push(m);
+    }
+    return out;
+}
+//# sourceMappingURL=messages.js.map

package/v3/@claude-flow/cli/dist/src/funnel/power-saver-notifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Power-saver notifier — ADR-314 §A out-of-band signal path.
+ *
+ * Structural mirror of rate-limit-notifier.ts, same self-reported/manual
+ * constraint (ADR-312's detection gap applies unchanged — ruflo cannot read
+ * "your account is at 20%" any more than it can read "you are rate
+ * limited"). Deliberately a SEPARATE flag from rate-limited: "running low,
+ * want to proactively conserve" (still have capacity) and "blocked" (zero
+ * capacity left) are different urgencies — conflating them would mean
+ * power-saver mode never fires until you're already blocked (too late to
+ * have conserved anything).
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/quota-status.json = { low: bool, since: ISO, cleared: ISO|null, lastToggleAt: ISO|null }
+ *
+ * Same 6h TTL rationale as rate-limit-notifier.ts, and the same ADR-314 §D1
+ * toggle cooldown (10 min) — a self-reported flag with zero server-side
+ * verification needs at least this much client-side friction against
+ * casual always-on gaming.
+ */
+export declare const QUOTA_STATUS_FILE = "quota-status.json";
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export declare const QUOTA_LOW_TTL_MS: number;
+export interface QuotaLowStatus {
+    low: boolean;
+    since: string | null;
+    cleared: string | null;
+    lastToggleAt: string | null;
+}
+/** Read the current power-saver status. Never throws. Applies the TTL. */
+export declare function readQuotaLowStatus(now?: Date): QuotaLowStatus;
+/**
+ * Mark quota as running low — idempotent, cooldown-gated (ADR-314 §D1).
+ * Returns false when the cooldown blocks the flip (not yet applied).
+ */
+export declare function markQuotaLow(now?: Date): boolean;
+/** Clear power-saver status. Cooldown-gated the same way as the mark direction. */
+export declare function clearQuotaLowStatus(now?: Date): boolean;
+/**
+ * User-facing single-line summary — plain text, no ANSI. Returns null when
+ * not flagged low (no surface).
+ */
+export declare function quotaLowNotice(now?: Date): string | null;
+//# sourceMappingURL=power-saver-notifier.d.ts.map

package/v3/@claude-flow/cli/dist/src/funnel/power-saver-notifier.js

@@ -0,0 +1,92 @@
+/**
+ * Power-saver notifier — ADR-314 §A out-of-band signal path.
+ *
+ * Structural mirror of rate-limit-notifier.ts, same self-reported/manual
+ * constraint (ADR-312's detection gap applies unchanged — ruflo cannot read
+ * "your account is at 20%" any more than it can read "you are rate
+ * limited"). Deliberately a SEPARATE flag from rate-limited: "running low,
+ * want to proactively conserve" (still have capacity) and "blocked" (zero
+ * capacity left) are different urgencies — conflating them would mean
+ * power-saver mode never fires until you're already blocked (too late to
+ * have conserved anything).
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/quota-status.json = { low: bool, since: ISO, cleared: ISO|null, lastToggleAt: ISO|null }
+ *
+ * Same 6h TTL rationale as rate-limit-notifier.ts, and the same ADR-314 §D1
+ * toggle cooldown (10 min) — a self-reported flag with zero server-side
+ * verification needs at least this much client-side friction against
+ * casual always-on gaming.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { cooldownActive } from './toggle-cooldown.js';
+export const QUOTA_STATUS_FILE = 'quota-status.json';
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export const QUOTA_LOW_TTL_MS = 6 * 60 * 60 * 1000;
+/** Read the current power-saver status. Never throws. Applies the TTL. */
+export function readQuotaLowStatus(now = new Date()) {
+    const raw = readStateJson(QUOTA_STATUS_FILE);
+    const status = {
+        low: raw?.low ?? false,
+        since: raw?.since ?? null,
+        cleared: raw?.cleared ?? null,
+        lastToggleAt: raw?.lastToggleAt ?? null,
+    };
+    if (status.low && status.since) {
+        const since = Date.parse(status.since);
+        if (!Number.isNaN(since) && now.getTime() - since >= QUOTA_LOW_TTL_MS) {
+            return { low: false, since: status.since, cleared: now.toISOString(), lastToggleAt: status.lastToggleAt };
+        }
+    }
+    return status;
+}
+/**
+ * Mark quota as running low — idempotent, cooldown-gated (ADR-314 §D1).
+ * Returns false when the cooldown blocks the flip (not yet applied).
+ */
+export function markQuotaLow(now = new Date()) {
+    const current = readQuotaLowStatus(now);
+    if (current.low && current.since)
+        return true; // already flagged, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(QUOTA_STATUS_FILE, {
+        low: true,
+        since: current.since ?? now.toISOString(),
+        cleared: null,
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/** Clear power-saver status. Cooldown-gated the same way as the mark direction. */
+export function clearQuotaLowStatus(now = new Date()) {
+    const current = readQuotaLowStatus(now);
+    if (!current.low)
+        return true; // already clear, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(QUOTA_STATUS_FILE, {
+        low: false,
+        since: current.since,
+        cleared: now.toISOString(),
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * User-facing single-line summary — plain text, no ANSI. Returns null when
+ * not flagged low (no surface).
+ */
+export function quotaLowNotice(now = new Date()) {
+    const status = readQuotaLowStatus(now);
+    if (!status.low)
+        return null;
+    const since = status.since ? Date.parse(status.since) : NaN;
+    if (Number.isNaN(since)) {
+        return 'Power saver mode active · manage: ruflo proxy power-saver-disable';
+    }
+    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 `Power saver mode active (${when}) · manage: ruflo proxy power-saver-disable`;
+}
+//# sourceMappingURL=power-saver-notifier.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * 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 type { FunnelEnabledDecision } from './types.js';
+export declare function resolveFunnelEnabled(cwd?: string, env?: NodeJS.ProcessEnv): FunnelEnabledDecision;
+//# sourceMappingURL=precedence.d.ts.map

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