@claude-flow/cli 3.25.5 → 3.26.0

package/dist/src/funnel/consent.js

@@ -0,0 +1,55 @@
+/**
+ * Consent domains and versioned receipts — ADR-302.
+ *
+ * Four+ distinct decisions, never bundled: account, proxy-install,
+ * telemetry, cloud-routing, hosted-memory. A receipt is written on both
+ * grant AND decline (a decline is a decision, not an absence). A stale
+ * policyVersion means the consent must be re-asked before the capability
+ * activates — never silently carried forward.
+ */
+import { CONSENT_POLICY_VERSION } from './types.js';
+import { readStateJson, writeStateJson } from './state.js';
+const CONSENT_FILE = 'consent.json';
+export const CONSENT_DOMAINS = [
+    'account',
+    'proxy-install',
+    'telemetry',
+    'cloud-routing',
+    'hosted-memory',
+    'sponsored-downtime',
+    'power-saver',
+    'training-data-sharing',
+    'advisor-tips',
+];
+export function readConsents() {
+    return readStateJson(CONSENT_FILE) ?? {};
+}
+export function getConsent(domain) {
+    const file = readConsents();
+    return (file[domain] ?? { granted: false, policyVersion: CONSENT_POLICY_VERSION, at: null, surface: null });
+}
+/**
+ * Effective consent: granted AND at the current policy version. A receipt
+ * from an older policy version is treated as not-consented (re-ask, never
+ * carry forward).
+ */
+export function hasConsent(domain) {
+    const r = getConsent(domain);
+    return r.granted === true && r.at !== null && r.policyVersion === CONSENT_POLICY_VERSION;
+}
+export function recordConsent(domain, granted, surface, now = new Date()) {
+    const file = readConsents();
+    const receipt = {
+        granted,
+        policyVersion: CONSENT_POLICY_VERSION,
+        at: now.toISOString(),
+        surface,
+    };
+    file[domain] = receipt;
+    writeStateJson(CONSENT_FILE, file);
+    return receipt;
+}
+export function revokeConsent(domain, surface) {
+    return recordConsent(domain, false, surface);
+}
+//# sourceMappingURL=consent.js.map

package/dist/src/funnel/credit-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Credit-error taxonomy and fail-closed classifier — ADR-303.
+ *
+ * Adapters map machine-readable provider codes into the canonical
+ * CreditErrorCode enum. Message text is NEVER parsed. Anything unmapped
+ * stays unclassified (confidence 0) and falls through to the ordinary
+ * error path. Only COGNITUM_CREDIT_EXHAUSTED — asserted by the Cognitum
+ * ledger, the single credit authority — may trigger the funnel surface.
+ */
+import { type NormalizedCreditError } from './types.js';
+export interface ProviderErrorLike {
+    /** Machine-readable provider error code (e.g. `error.type` / `error.code`). */
+    providerCode?: string;
+    /** HTTP status, when the transport exposes one. */
+    status?: number;
+}
+export declare function classifyCreditError(err: ProviderErrorLike): NormalizedCreditError;
+export interface CreditPromptSession {
+    creditPromptShown: boolean;
+}
+/**
+ * The ADR-303 gate, fail-closed and frequency-capped: fires only for a
+ * confident, non-retryable Cognitum-ledger exhaustion, at most once per
+ * session. Everything else falls through to the ordinary error path.
+ */
+export declare function shouldShowCreditRecovery(error: NormalizedCreditError, session: CreditPromptSession): boolean;
+/** Full contextual screen (interactive TTY, first occurrence). */
+export declare function renderCreditRecovery(authenticated: boolean): string;
+/** Single-line hint (non-TTY, CI, or repeat occurrences in a session). */
+export declare const CREDIT_RECOVERY_HINT = "Hint: ruflo auth login enables the free local Meta LLM proxy";
+//# sourceMappingURL=credit-errors.d.ts.map

package/dist/src/funnel/credit-errors.js

@@ -0,0 +1,88 @@
+/**
+ * Credit-error taxonomy and fail-closed classifier — ADR-303.
+ *
+ * Adapters map machine-readable provider codes into the canonical
+ * CreditErrorCode enum. Message text is NEVER parsed. Anything unmapped
+ * stays unclassified (confidence 0) and falls through to the ordinary
+ * error path. Only COGNITUM_CREDIT_EXHAUSTED — asserted by the Cognitum
+ * ledger, the single credit authority — may trigger the funnel surface.
+ */
+import { CreditErrorCode } from './types.js';
+/**
+ * Provider-code → canonical-code table. Keys are exact machine-readable
+ * code strings from provider error payloads (mirrors the ADR-308 server
+ * taxonomy 1:1). Versioned by code review; unmapped codes land nowhere.
+ */
+const PROVIDER_CODE_TABLE = {
+    // Cognitum ledger (the single credit authority — ADR-303)
+    cognitum_credit_exhausted: { code: CreditErrorCode.COGNITUM_CREDIT_EXHAUSTED, retryable: false },
+    // Upstream provider quota/billing — NOT a Cognitum upsell moment
+    insufficient_quota: { code: CreditErrorCode.PROVIDER_QUOTA_EXHAUSTED, retryable: false },
+    billing_hard_limit_reached: { code: CreditErrorCode.PROVIDER_QUOTA_EXHAUSTED, retryable: false },
+    quota_exceeded: { code: CreditErrorCode.PROVIDER_QUOTA_EXHAUSTED, retryable: false },
+    // Retryable rate limits
+    rate_limit_exceeded: { code: CreditErrorCode.PROVIDER_RATE_LIMITED, retryable: true },
+    rate_limit_error: { code: CreditErrorCode.PROVIDER_RATE_LIMITED, retryable: true },
+    overloaded_error: { code: CreditErrorCode.SERVICE_UNAVAILABLE, retryable: true },
+    // Auth
+    authentication_error: { code: CreditErrorCode.AUTHENTICATION_FAILED, retryable: false },
+    invalid_api_key: { code: CreditErrorCode.AUTHENTICATION_FAILED, retryable: false },
+    permission_error: { code: CreditErrorCode.AUTHENTICATION_FAILED, retryable: false },
+    // Outages
+    api_error: { code: CreditErrorCode.SERVICE_UNAVAILABLE, retryable: true },
+    service_unavailable: { code: CreditErrorCode.SERVICE_UNAVAILABLE, retryable: true },
+};
+export function classifyCreditError(err) {
+    const key = err.providerCode?.trim().toLowerCase();
+    if (key && Object.prototype.hasOwnProperty.call(PROVIDER_CODE_TABLE, key)) {
+        const mapped = PROVIDER_CODE_TABLE[key];
+        return { code: mapped.code, confidence: 1, retryable: mapped.retryable, cause: err };
+    }
+    // Status-only signals are structural (401/403 → auth; 5xx → outage), but a
+    // bare 429 is ambiguous between rate-limit and quota — leave it unmapped.
+    if (err.status === 401 || err.status === 403) {
+        return { code: CreditErrorCode.AUTHENTICATION_FAILED, confidence: 1, retryable: false, cause: err };
+    }
+    if (err.status !== undefined && err.status >= 500) {
+        return { code: CreditErrorCode.SERVICE_UNAVAILABLE, confidence: 1, retryable: true, cause: err };
+    }
+    return { code: null, confidence: 0, retryable: false, cause: err };
+}
+/**
+ * The ADR-303 gate, fail-closed and frequency-capped: fires only for a
+ * confident, non-retryable Cognitum-ledger exhaustion, at most once per
+ * session. Everything else falls through to the ordinary error path.
+ */
+export function shouldShowCreditRecovery(error, session) {
+    return (error.code === CreditErrorCode.COGNITUM_CREDIT_EXHAUSTED &&
+        error.confidence === 1 &&
+        !error.retryable &&
+        !session.creditPromptShown);
+}
+/** Full contextual screen (interactive TTY, first occurrence). */
+export function renderCreditRecovery(authenticated) {
+    const lines = [
+        'Daily hosted credits exhausted.',
+        '',
+        'Continue immediately by enabling',
+        'your free local Meta LLM Proxy.',
+        '',
+        'Benefits',
+        '  ✓ Unlimited local requests',
+        '  ✓ Automatic model routing',
+        '  ✓ Lower latency',
+        '  ✓ Privacy preserving',
+        '  ✓ Cloud fallback',
+        '',
+    ];
+    if (authenticated) {
+        lines.push('Start local proxy?', '  ruflo proxy enable');
+    }
+    else {
+        lines.push('Sign in:', '  ruflo auth login');
+    }
+    return lines.join('\n');
+}
+/** Single-line hint (non-TTY, CI, or repeat occurrences in a session). */
+export const CREDIT_RECOVERY_HINT = 'Hint: ruflo auth login enables the free local Meta LLM proxy';
+//# sourceMappingURL=credit-errors.js.map

package/dist/src/funnel/credit-notifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Credit-exhaustion notifier — writes a marker file so the ADR-303 recovery
+ * surface fires on the next appropriate command render, and keeps a short
+ * user-visible notification in `~/.ruflo/credit-status.json`.
+ *
+ * This is NOT the ADR-303 credit-error classifier — that lives in
+ * `credit-errors.ts` and reads provider error codes to decide when a
+ * credit surface fires *during* a command. This module is the OUT-OF-BAND
+ * signal path: the analytics transport detected a credit-exhausted
+ * response (HTTP 402 or ADR-303 machine-readable code), and we need to
+ * warn the user asynchronously.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/credit-status.json = { exhausted: bool, since: ISO, cleared: ISO|null }
+ *
+ * Cleared automatically when the user opens the enrollment / signup
+ * surface, or explicitly via `ruflo funnel credit-clear`.
+ */
+export declare const CREDIT_STATUS_FILE = "credit-status.json";
+export interface CreditStatus {
+    exhausted: boolean;
+    since: string | null;
+    cleared: string | null;
+}
+/** Read the current credit status. Never throws. */
+export declare function readCreditStatus(): CreditStatus;
+/**
+ * Mark credit as exhausted — 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.
+ */
+export declare function markCreditExhausted(now?: Date): void;
+/**
+ * Clear credit-exhaustion status. Called when the user completes signup or
+ * runs `ruflo funnel credit-clear`. `cleared` is stamped so the previous
+ * `since` remains inspectable for one recovery cycle.
+ */
+export declare function clearCreditStatus(now?: Date): void;
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when credit isn't exhausted (no surface).
+ */
+export declare function creditExhaustedNotice(now?: Date): string | null;
+//# sourceMappingURL=credit-notifier.d.ts.map

package/dist/src/funnel/credit-notifier.js

@@ -0,0 +1,74 @@
+/**
+ * Credit-exhaustion notifier — writes a marker file so the ADR-303 recovery
+ * surface fires on the next appropriate command render, and keeps a short
+ * user-visible notification in `~/.ruflo/credit-status.json`.
+ *
+ * This is NOT the ADR-303 credit-error classifier — that lives in
+ * `credit-errors.ts` and reads provider error codes to decide when a
+ * credit surface fires *during* a command. This module is the OUT-OF-BAND
+ * signal path: the analytics transport detected a credit-exhausted
+ * response (HTTP 402 or ADR-303 machine-readable code), and we need to
+ * warn the user asynchronously.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/credit-status.json = { exhausted: bool, since: ISO, cleared: ISO|null }
+ *
+ * Cleared automatically when the user opens the enrollment / signup
+ * surface, or explicitly via `ruflo funnel credit-clear`.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+export const CREDIT_STATUS_FILE = 'credit-status.json';
+/** Read the current credit status. Never throws. */
+export function readCreditStatus() {
+    const raw = readStateJson(CREDIT_STATUS_FILE);
+    return {
+        exhausted: raw?.exhausted ?? false,
+        since: raw?.since ?? null,
+        cleared: raw?.cleared ?? null,
+    };
+}
+/**
+ * Mark credit as exhausted — 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.
+ */
+export function markCreditExhausted(now = new Date()) {
+    const current = readCreditStatus();
+    if (current.exhausted && current.since)
+        return; // already flagged
+    writeStateJson(CREDIT_STATUS_FILE, {
+        exhausted: true,
+        since: current.since ?? now.toISOString(),
+        cleared: null,
+    });
+}
+/**
+ * Clear credit-exhaustion status. Called when the user completes signup or
+ * runs `ruflo funnel credit-clear`. `cleared` is stamped so the previous
+ * `since` remains inspectable for one recovery cycle.
+ */
+export function clearCreditStatus(now = new Date()) {
+    const current = readCreditStatus();
+    writeStateJson(CREDIT_STATUS_FILE, {
+        exhausted: false,
+        since: current.since,
+        cleared: now.toISOString(),
+    });
+}
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when credit isn't exhausted (no surface).
+ */
+export function creditExhaustedNotice(now = new Date()) {
+    const status = readCreditStatus();
+    if (!status.exhausted)
+        return null;
+    const since = status.since ? Date.parse(status.since) : NaN;
+    if (Number.isNaN(since)) {
+        return 'Cognitum credits exhausted · run: ruflo funnel signup';
+    }
+    const ageHours = Math.max(0, Math.round((now.getTime() - since) / (60 * 60 * 1000)));
+    const when = ageHours < 1 ? 'just now' : ageHours < 24 ? `${ageHours}h ago` : `${Math.round(ageHours / 24)}d ago`;
+    return `Cognitum credits exhausted (${when}) · run: ruflo funnel signup`;
+}
+//# sourceMappingURL=credit-notifier.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Existing-install disclosure gate — ADR-301, amended by ADR-311 to source
+ * the disclosure MESSAGE itself from the remote feed rather than hardcoding
+ * it in the CLI. Everything about WHETHER/WHEN to show a disclosure stays
+ * local (state machine below); everything about WHAT it says comes from
+ * the same remote pool as tips/promos, validated through the identical
+ * ADR-301 content pipeline (isValidMessage in messages.ts).
+ *
+ * Invariants (release-blocking, tested):
+ *   - No promotional content before disclosure.
+ *   - The manage instruction appears in the disclosure text itself.
+ *   - Shown once per user (user-level receipt), not once per project.
+ *   - Declining disables all funnel surfaces (enforced in precedence.ts).
+ *   - Fail-closed: if the remote feed has never successfully populated a
+ *     disclosure-class message, there is nothing to show — no local
+ *     fallback text exists (ADR-311 "zero local promo content").
+ *
+ * The disclosure text stays on the promo row for a grace window after its
+ * first render so a single flash can't count as "the user was told"; only
+ * after the window do promotional messages become eligible.
+ */
+import type { DisclosureRecord, FunnelMessage } from './types.js';
+/** How long the disclosure text keeps the row before promo becomes eligible. */
+export declare const DISCLOSURE_GRACE_MS: number;
+export declare const DISCLOSURE_ROTATION_SLOT_MS: number;
+/**
+ * Deterministic slot-based selection over the remote disclosure pool — no
+ * RNG so the choice is reproducible for a given wall-clock instant. Returns
+ * null when the pool is empty (cold start before first fetch, or the remote
+ * feed is unreachable) — the caller must treat null as "show nothing".
+ */
+export declare function selectDisclosureMessage(now?: Date): FunnelMessage | null;
+export declare function getDisclosure(): DisclosureRecord;
+/** Record that the disclosure text was rendered (idempotent). */
+export declare function recordDisclosureShown(now?: Date): DisclosureRecord;
+/** User explicitly declined (e.g. `ruflo funnel disable`). */
+export declare function recordDisclosureDeclined(now?: Date): DisclosureRecord;
+/** Re-enable after a prior decline (explicit user action only). */
+export declare function recordDisclosureReenabled(now?: Date): DisclosureRecord;
+/**
+ * Whether promotional/educational messages may render. True only after the
+ * disclosure was shown AND its grace window has elapsed. While the window is
+ * open the row must carry the disclosure text itself.
+ */
+export declare function promoEligible(now?: Date): boolean;
+//# sourceMappingURL=disclosure.d.ts.map

package/dist/src/funnel/disclosure.js

@@ -0,0 +1,97 @@
+/**
+ * Existing-install disclosure gate — ADR-301, amended by ADR-311 to source
+ * the disclosure MESSAGE itself from the remote feed rather than hardcoding
+ * it in the CLI. Everything about WHETHER/WHEN to show a disclosure stays
+ * local (state machine below); everything about WHAT it says comes from
+ * the same remote pool as tips/promos, validated through the identical
+ * ADR-301 content pipeline (isValidMessage in messages.ts).
+ *
+ * Invariants (release-blocking, tested):
+ *   - No promotional content before disclosure.
+ *   - The manage instruction appears in the disclosure text itself.
+ *   - Shown once per user (user-level receipt), not once per project.
+ *   - Declining disables all funnel surfaces (enforced in precedence.ts).
+ *   - Fail-closed: if the remote feed has never successfully populated a
+ *     disclosure-class message, there is nothing to show — no local
+ *     fallback text exists (ADR-311 "zero local promo content").
+ *
+ * The disclosure text stays on the promo row for a grace window after its
+ * first render so a single flash can't count as "the user was told"; only
+ * after the window do promotional messages become eligible.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { getRemoteMessages } from './message-transport.js';
+const DISCLOSURE_FILE = 'funnel-disclosure.json';
+/** How long the disclosure text keeps the row before promo becomes eligible. */
+export const DISCLOSURE_GRACE_MS = 24 * 60 * 60 * 1000; // 24h
+// One disclosure variant per 5-minute wall-clock slot. Longer than the
+// 20-second rotation cadence so a user watching the statusline sees the
+// same variant long enough to read it, but short enough that a fresh
+// session gets a different one than the previous one did.
+export const DISCLOSURE_ROTATION_SLOT_MS = 5 * 60 * 1000;
+/** Remote-cached messages tagged class==='disclosure' — the only source. */
+function getDisclosureMessagePool() {
+    return getRemoteMessages().filter((m) => m.class === 'disclosure');
+}
+/**
+ * Deterministic slot-based selection over the remote disclosure pool — no
+ * RNG so the choice is reproducible for a given wall-clock instant. Returns
+ * null when the pool is empty (cold start before first fetch, or the remote
+ * feed is unreachable) — the caller must treat null as "show nothing".
+ */
+export function selectDisclosureMessage(now = new Date()) {
+    const pool = getDisclosureMessagePool();
+    if (pool.length === 0)
+        return null;
+    const slot = Math.floor(now.getTime() / DISCLOSURE_ROTATION_SLOT_MS);
+    return pool[slot % pool.length];
+}
+export function getDisclosure() {
+    const rec = readStateJson(DISCLOSURE_FILE);
+    if (rec && isValidState(rec.state))
+        return rec;
+    return { state: 'never_seen', firstShownAt: null };
+}
+function isValidState(s) {
+    return s === 'never_seen' || s === 'disclosed_enabled' || s === 'disclosed_disabled';
+}
+/** Record that the disclosure text was rendered (idempotent). */
+export function recordDisclosureShown(now = new Date()) {
+    const current = getDisclosure();
+    if (current.state !== 'never_seen')
+        return current;
+    const rec = { state: 'disclosed_enabled', firstShownAt: now.toISOString() };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/** User explicitly declined (e.g. `ruflo funnel disable`). */
+export function recordDisclosureDeclined(now = new Date()) {
+    const current = getDisclosure();
+    const rec = {
+        state: 'disclosed_disabled',
+        firstShownAt: current.firstShownAt ?? now.toISOString(),
+    };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/** Re-enable after a prior decline (explicit user action only). */
+export function recordDisclosureReenabled(now = new Date()) {
+    const rec = { state: 'disclosed_enabled', firstShownAt: now.toISOString() };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/**
+ * Whether promotional/educational messages may render. True only after the
+ * disclosure was shown AND its grace window has elapsed. While the window is
+ * open the row must carry the disclosure text itself.
+ */
+export function promoEligible(now = new Date()) {
+    const rec = getDisclosure();
+    if (rec.state !== 'disclosed_enabled' || !rec.firstShownAt)
+        return false;
+    const first = Date.parse(rec.firstShownAt);
+    if (Number.isNaN(first))
+        return false;
+    return now.getTime() - first >= DISCLOSURE_GRACE_MS;
+}
+//# sourceMappingURL=disclosure.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Post-initialization capability enrollment — ADR-302.
+ *
+ * One-time, non-blocking, skippable. Gates, all of which must pass:
+ *   - interactive TTY (never in CI / piped / automation)
+ *   - not skipped via --no-signup
+ *   - funnel enabled under the ADR-305 precedence chain
+ *   - never shown before (user-level record, not per-project)
+ *
+ * Accepting authorizes exactly ONE thing: a pointer to `ruflo auth login`.
+ * It does not install the proxy, does not enable telemetry, and does not
+ * enable cloud routing (separate consent domains — ADR-302). The enrollment
+ * outcome never affects init's exit code.
+ */
+interface EnrollmentRecord {
+    shownAt: string;
+    outcome: 'accepted' | 'skipped';
+}
+export declare function getEnrollmentRecord(): EnrollmentRecord | null;
+export declare const ENROLLMENT_SCREEN: string;
+export declare const ENROLLMENT_SKIP_TEXT = "You can enable later:\n  ruflo auth login";
+export interface EnrollmentGateContext {
+    noSignup: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** All ADR-302 gates. Pure check — does not write state. */
+export declare function shouldOfferEnrollment(ctx: EnrollmentGateContext): boolean;
+/**
+ * Record the user's decision. Both accept and skip are terminal — the
+ * prompt never reappears (ADR-302). Accepting records the `account`
+ * consent receipt; skipping records the decline.
+ */
+export declare function recordEnrollmentOutcome(accepted: boolean, now?: Date): void;
+export {};
+//# sourceMappingURL=enrollment.d.ts.map

package/dist/src/funnel/enrollment.js

@@ -0,0 +1,64 @@
+/**
+ * Post-initialization capability enrollment — ADR-302.
+ *
+ * One-time, non-blocking, skippable. Gates, all of which must pass:
+ *   - interactive TTY (never in CI / piped / automation)
+ *   - not skipped via --no-signup
+ *   - funnel enabled under the ADR-305 precedence chain
+ *   - never shown before (user-level record, not per-project)
+ *
+ * Accepting authorizes exactly ONE thing: a pointer to `ruflo auth login`.
+ * It does not install the proxy, does not enable telemetry, and does not
+ * enable cloud routing (separate consent domains — ADR-302). The enrollment
+ * outcome never affects init's exit code.
+ */
+import { isCI, isInteractive } from './environment.js';
+import { resolveFunnelEnabled } from './precedence.js';
+import { recordConsent } from './consent.js';
+import { readStateJson, writeStateJson } from './state.js';
+const ENROLLMENT_FILE = 'enrollment.json';
+export function getEnrollmentRecord() {
+    return readStateJson(ENROLLMENT_FILE);
+}
+export const ENROLLMENT_SCREEN = [
+    '────────────────────────────',
+    'Unlock additional capabilities?',
+    '',
+    '  ✓ Local Meta LLM Proxy',
+    '  ✓ Multi-model routing',
+    '  ✓ Hosted memory',
+    '  ✓ Enterprise rate limits',
+    '  ✓ Premium agents',
+    '  ✓ Cloud synchronization',
+    '',
+    'Free account: https://cognitum.one',
+].join('\n');
+export const ENROLLMENT_SKIP_TEXT = 'You can enable later:\n  ruflo auth login';
+/** All ADR-302 gates. Pure check — does not write state. */
+export function shouldOfferEnrollment(ctx) {
+    const env = ctx.env ?? process.env;
+    if (ctx.noSignup)
+        return false;
+    if (isCI(env))
+        return false;
+    if (!isInteractive())
+        return false;
+    if (!resolveFunnelEnabled(ctx.cwd ?? process.cwd(), env).enabled)
+        return false;
+    if (getEnrollmentRecord() !== null)
+        return false; // one-time only
+    return true;
+}
+/**
+ * Record the user's decision. Both accept and skip are terminal — the
+ * prompt never reappears (ADR-302). Accepting records the `account`
+ * consent receipt; skipping records the decline.
+ */
+export function recordEnrollmentOutcome(accepted, now = new Date()) {
+    writeStateJson(ENROLLMENT_FILE, {
+        shownAt: now.toISOString(),
+        outcome: accepted ? 'accepted' : 'skipped',
+    });
+    recordConsent('account', accepted, 'post-init', now);
+}
+//# sourceMappingURL=enrollment.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Environment gates for funnel surfaces (ADR-301/302).
+ *
+ * CI and non-interactive environments never see funnel content; reduced
+ * motion / screen readers get static text only (which is all the funnel
+ * renders anyway — there is deliberately no animation path in this module).
+ */
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+export declare function isInteractive(): boolean;
+/**
+ * Statusline invocations are spawned by an interactive host (Claude Code)
+ * with piped stdio, so isTTY is false there even though the session is
+ * interactive. Surfaces pass their own interactivity signal; this helper is
+ * the strict check used by directly-invoked prompts (init enrollment).
+ */
+export declare function reducedMotion(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=environment.d.ts.map

package/dist/src/funnel/environment.js

@@ -0,0 +1,39 @@
+/**
+ * Environment gates for funnel surfaces (ADR-301/302).
+ *
+ * CI and non-interactive environments never see funnel content; reduced
+ * motion / screen readers get static text only (which is all the funnel
+ * renders anyway — there is deliberately no animation path in this module).
+ */
+const CI_ENV_VARS = [
+    'CI',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+    'JENKINS_URL',
+    'TEAMCITY_VERSION',
+    'TF_BUILD', // Azure Pipelines
+];
+export function isCI(env = process.env) {
+    return CI_ENV_VARS.some((v) => {
+        const val = env[v];
+        return val !== undefined && val !== '' && val !== '0' && val.toLowerCase?.() !== 'false';
+    });
+}
+export function isInteractive() {
+    return Boolean(process.stdout.isTTY && process.stdin.isTTY);
+}
+/**
+ * Statusline invocations are spawned by an interactive host (Claude Code)
+ * with piped stdio, so isTTY is false there even though the session is
+ * interactive. Surfaces pass their own interactivity signal; this helper is
+ * the strict check used by directly-invoked prompts (init enrollment).
+ */
+export function reducedMotion(env = process.env) {
+    return Boolean(env.NO_COLOR !== undefined ||
+        env.RUFLO_REDUCED_MOTION === '1' ||
+        env.TERM === 'dumb');
+}
+//# sourceMappingURL=environment.js.map

package/dist/src/funnel/event-transport.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Event transport — batches the local funnel event queue and posts it to the
+ * Cognitum analytics Cloud Function (ADR-308 endpoint contract).
+ *
+ * Design discipline (ADR-308 client failure policy — all normative):
+ *   1. Telemetry never blocks the CLI. Every network call is best-effort,
+ *      capped by a short timeout, and swallows every error path.
+ *   2. Events are LOCAL FIRST. The queue in `events.ts` accumulates
+ *      regardless of API reachability. This transport is the flush layer.
+ *   3. Idempotency: every batch carries a UUIDv4 idempotency key so a retry
+ *      never double-counts (ADR-308 idempotent-batches invariant).
+ *   4. Exponential backoff on transient failures. Successful flushes stamp
+ *      a "last flush" timestamp so we don't hammer the API each render.
+ *   5. Consent-gated. Zero network activity when telemetry consent is off.
+ *   6. Bounded. Never send more than MAX_BATCH events at once, so a large
+ *      backlog doesn't blow the endpoint request-size limit.
+ *   7. Credit-exhaustion detection. If the endpoint replies 402 (Payment
+ *      Required) or the body carries the ADR-303
+ *      `COGNITUM_CREDIT_EXHAUSTED` code, we surface via `credit-notifier.ts`
+ *      — the same recovery UX ADR-303 already ships.
+ */
+/**
+ * Default endpoint — the ruflo-funnel-analytics endpoint on the ruv.io
+ * domain, mapped via Cloud Run domain mapping to the cognitum-analytics
+ * Cloud Function on cognitum-20260110. Overridable by env for staging or
+ * self-hosted deploys. The domain choice is deliberate: an rUv-authored
+ * OSS project's telemetry endpoint belongs on rUv's own domain, not on
+ * cognitum.one — that keeps the CLI attribution honest.
+ */
+export declare const DEFAULT_ENDPOINT: string;
+/** Cap per POST — server enforces its own limits too; this is a safety net. */
+export declare const MAX_BATCH = 100;
+/** Min interval between flushes (ms). Rate limits the client from within. */
+export declare const MIN_FLUSH_INTERVAL_MS = 60000;
+/** POST timeout — telemetry must not stall the CLI. */
+export declare const FLUSH_TIMEOUT_MS = 4000;
+/**
+ * Best-effort flush of the local event queue to the endpoint. Returns a
+ * summary the CLI can log at --verbose; the caller should never fail on it.
+ */
+export declare function flushEvents(opts?: {
+    endpoint?: string;
+    release?: string;
+    force?: boolean;
+    now?: Date;
+}): Promise<{
+    flushed: number;
+    skipped: string | null;
+    status?: number;
+}>;
+//# sourceMappingURL=event-transport.d.ts.map