@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/funnel/advisor-tip.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Advisor co-pilot tip — ADR-316. A periodic, consent-gated, budget-capped
+ * suggestion generated by ruflo's existing Fable Advisor Harness
+ * (services/fable-harness.ts, ADR-172), surfaced in the local insight
+ * ticker (insights.ts) alongside the CVE/uncommitted/power-saver signals.
+ *
+ * This is the ONE insight source that spends real money and makes a real
+ * network call — every other source in insights.ts is synchronous, local,
+ * $0 by construction. Three hard gates keep that safe:
+ *   1. consent: 'advisor-tips' domain (types.ts/consent.ts), never bundled
+ *      with anything else, off by default.
+ *   2. cooldown: at most once per ADVISOR_REFRESH_TTL_MS regardless of how
+ *      many sessions run in that window — a file-based TTL checked BEFORE
+ *      spawning, not a per-call budget hope.
+ *   3. budget: FableHarness's own --max-budget-usd hard cap, passed through
+ *      to the underlying `claude -p` call.
+ *
+ * The snapshot sent to the model is built ONLY from the same structural
+ * signals insights.ts already uses (funnel/local-signals.ts) — never raw
+ * prompts, commands, or file contents. Matches ADR-309's "no raw content,
+ * ever" bar even though ADR-309 is about telemetry and this is a different,
+ * separately-consented data flow (an opt-in advisor query, not analytics).
+ *
+ * Cheapness/latency discipline for the CALLER (never this module itself):
+ * refreshAdvisorTipIfStale performs a real network-bound `claude -p` spawn
+ * when stale — callers MUST run it from a properly-awaited, DETACHED
+ * background process (mirroring the funnel-cache fix's
+ * spawnDetachedFunnelRefresh pattern), never inline in a statusline render.
+ */
+import { FableHarness, type CoPilotSnapshot } from '../services/fable-harness.js';
+/** At most one real spend per real day, regardless of session count. */
+export declare const ADVISOR_REFRESH_TTL_MS: number;
+/** Conservative default — one adviseCoPilotTip call is a single, unbatched
+ * item, so the ~$0.34 clean-cwd anchor (not the $0.02 batched anchor)
+ * applies. Override via RUFLO_ADVISOR_MAX_BUDGET_USD for advanced users. */
+export declare const ADVISOR_DEFAULT_BUDGET_USD = 0.4;
+export interface CachedAdvisorTip {
+    headline: string;
+    detail: string;
+}
+/** Synchronous, $0, no network — safe to call from the insight ticker's hot path. */
+export declare function readAdvisorTip(now?: Date): CachedAdvisorTip | null;
+export interface AdvisorRefreshResult {
+    refreshed: boolean;
+    reason?: 'not-consented' | 'fresh' | 'no-tip' | 'error';
+}
+/**
+ * Refresh the cached advisor tip if consent is granted AND the cache is
+ * stale. Spends real money via FableHarness exactly once per call site,
+ * gated by the TTL check above — callers get to decide cadence (e.g.
+ * "call this on every session-restore"; the TTL makes repeated calls cheap
+ * no-ops within the same window).
+ */
+export declare function refreshAdvisorTipIfStale(snapshot: CoPilotSnapshot, opts?: {
+    now?: Date;
+    harness?: FableHarness;
+}): Promise<AdvisorRefreshResult>;
+//# sourceMappingURL=advisor-tip.d.ts.map

package/dist/src/funnel/advisor-tip.js

@@ -0,0 +1,92 @@
+/**
+ * Advisor co-pilot tip — ADR-316. A periodic, consent-gated, budget-capped
+ * suggestion generated by ruflo's existing Fable Advisor Harness
+ * (services/fable-harness.ts, ADR-172), surfaced in the local insight
+ * ticker (insights.ts) alongside the CVE/uncommitted/power-saver signals.
+ *
+ * This is the ONE insight source that spends real money and makes a real
+ * network call — every other source in insights.ts is synchronous, local,
+ * $0 by construction. Three hard gates keep that safe:
+ *   1. consent: 'advisor-tips' domain (types.ts/consent.ts), never bundled
+ *      with anything else, off by default.
+ *   2. cooldown: at most once per ADVISOR_REFRESH_TTL_MS regardless of how
+ *      many sessions run in that window — a file-based TTL checked BEFORE
+ *      spawning, not a per-call budget hope.
+ *   3. budget: FableHarness's own --max-budget-usd hard cap, passed through
+ *      to the underlying `claude -p` call.
+ *
+ * The snapshot sent to the model is built ONLY from the same structural
+ * signals insights.ts already uses (funnel/local-signals.ts) — never raw
+ * prompts, commands, or file contents. Matches ADR-309's "no raw content,
+ * ever" bar even though ADR-309 is about telemetry and this is a different,
+ * separately-consented data flow (an opt-in advisor query, not analytics).
+ *
+ * Cheapness/latency discipline for the CALLER (never this module itself):
+ * refreshAdvisorTipIfStale performs a real network-bound `claude -p` spawn
+ * when stale — callers MUST run it from a properly-awaited, DETACHED
+ * background process (mirroring the funnel-cache fix's
+ * spawnDetachedFunnelRefresh pattern), never inline in a statusline render.
+ */
+import { hasConsent } from './consent.js';
+import { readStateJson, writeStateJson } from './state.js';
+import { FableHarness } from '../services/fable-harness.js';
+const ADVISOR_CACHE_FILE = 'advisor-tip.json';
+/** At most one real spend per real day, regardless of session count. */
+export const ADVISOR_REFRESH_TTL_MS = 24 * 60 * 60 * 1000;
+/** Conservative default — one adviseCoPilotTip call is a single, unbatched
+ * item, so the ~$0.34 clean-cwd anchor (not the $0.02 batched anchor)
+ * applies. Override via RUFLO_ADVISOR_MAX_BUDGET_USD for advanced users. */
+export const ADVISOR_DEFAULT_BUDGET_USD = 0.4;
+/** Synchronous, $0, no network — safe to call from the insight ticker's hot path. */
+export function readAdvisorTip(now = new Date()) {
+    const cache = readStateJson(ADVISOR_CACHE_FILE);
+    // `!cache._ts` would wrongly treat a legitimate epoch-zero timestamp as
+    // absent (0 is falsy) — check the type explicitly instead.
+    if (!cache || !cache.headline || typeof cache._ts !== 'number')
+        return null;
+    if (now.getTime() - cache._ts >= ADVISOR_REFRESH_TTL_MS)
+        return null;
+    return { headline: cache.headline, detail: cache.detail ?? '' };
+}
+function isCacheStale(now) {
+    const cache = readStateJson(ADVISOR_CACHE_FILE);
+    if (!cache || typeof cache._ts !== 'number')
+        return true;
+    return now.getTime() - cache._ts >= ADVISOR_REFRESH_TTL_MS;
+}
+function resolveBudgetUsd() {
+    const raw = process.env.RUFLO_ADVISOR_MAX_BUDGET_USD;
+    const n = raw !== undefined ? Number(raw) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : ADVISOR_DEFAULT_BUDGET_USD;
+}
+/**
+ * Refresh the cached advisor tip if consent is granted AND the cache is
+ * stale. Spends real money via FableHarness exactly once per call site,
+ * gated by the TTL check above — callers get to decide cadence (e.g.
+ * "call this on every session-restore"; the TTL makes repeated calls cheap
+ * no-ops within the same window).
+ */
+export async function refreshAdvisorTipIfStale(snapshot, opts = {}) {
+    const now = opts.now ?? new Date();
+    if (!hasConsent('advisor-tips'))
+        return { refreshed: false, reason: 'not-consented' };
+    if (!isCacheStale(now))
+        return { refreshed: false, reason: 'fresh' };
+    const harness = opts.harness ?? new FableHarness({ maxBudgetUsd: resolveBudgetUsd() });
+    try {
+        const tip = await harness.adviseCoPilotTip(snapshot);
+        if (!tip) {
+            // The model looked and found nothing worth surfacing — still stamp
+            // _ts so we don't re-spend inside the same TTL window re-asking the
+            // same question and getting the same "nothing to say" answer.
+            writeStateJson(ADVISOR_CACHE_FILE, { _ts: now.getTime() });
+            return { refreshed: true, reason: 'no-tip' };
+        }
+        writeStateJson(ADVISOR_CACHE_FILE, { _ts: now.getTime(), headline: tip.headline, detail: tip.detail });
+        return { refreshed: true };
+    }
+    catch {
+        return { refreshed: false, reason: 'error' };
+    }
+}
+//# sourceMappingURL=advisor-tip.js.map

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

@@ -0,0 +1,37 @@
+export interface AttributionInput {
+    /** UTM `medium` — the surface (e.g. 'statusline', 'enrollment', 'exhaustion'). */
+    medium: string;
+    /** UTM `campaign` — the message kind ('disclosure' | 'promotional' | 'educational'). */
+    campaign: string;
+    /** UTM `content` — the specific message id ('promo-meta-llm-routing' etc.). */
+    content: string;
+    /** Static UTM `source` — always 'ruflo' but overridable for tests. */
+    source?: string;
+    /** Injectable for deterministic tests. Defaults to the live clock. */
+    now?: Date;
+}
+/**
+ * Return `url` with UTM parameters appended, and — when telemetry consent is
+ * granted — a `fid` query parameter carrying the pseudonymous funnel ID.
+ * Preserves any query parameters the base URL already carried.
+ */
+export declare function attributionUrl(url: string, input: AttributionInput): string;
+/**
+ * Wrap the target URL in a server-side click-redirect so the analytics
+ * function fires a `promo_open` event + records coarse geo before 302ing to
+ * the real destination.
+ *
+ * Only applied to promotional messages (they have a real URL destination).
+ * Disclosure/educational rows call attributionUrl directly.
+ *
+ * The click endpoint URL structure is:
+ *   https://funnel.ruv.io/v1/click/{messageId}?to=<utm-decorated-target>
+ *
+ * The server validates `to` against its own host allowlist, records the
+ * event, and 302s. If the click endpoint is unreachable at OSC 8 time,
+ * the browser falls back to the terminal's normal error page — but since
+ * this is a rare failure path and impressions are already recorded, the
+ * loss is bounded.
+ */
+export declare function clickTrackedUrl(messageId: string, targetUrl: string, input: AttributionInput): string;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/src/funnel/attribution.js

@@ -0,0 +1,101 @@
+/**
+ * Attribution URL builder — appends UTM parameters and the pseudonymous funnel
+ * ID to outbound funnel links so cognitum.one traffic analytics can attribute
+ * a landing back to the surface, message, and campaign that produced it
+ * (ADR-305 measurement plane).
+ *
+ * Failure discipline (ADR-301 no-runtime-network invariant, Phase 1):
+ *   - This function is PURE — it never makes a network call. Attribution is
+ *     shipped as query params on a link the user's own browser resolves; the
+ *     CLI has zero runtime dependency on cognitum.one being reachable.
+ *     If the whole API is down, the OSC 8 label still renders correctly, the
+ *     click still leaves the terminal, and only the landing page fails (which
+ *     is a browser-visible problem, not a statusline problem).
+ *   - If the base URL is malformed, we return it verbatim rather than
+ *     synthesizing a broken analytics endpoint. The OSC 8 renderer then
+ *     re-validates the host against its allowlist and, on failure, drops
+ *     the escape entirely and shows the plain label — never a raw URL.
+ *
+ * Privacy discipline (ADR-309):
+ *   - `fid` (the pseudonymous funnel ID) is appended only when telemetry
+ *     consent is present. Without consent, getFunnelId() returns null and
+ *     the URL carries only the UTM fields — same landing page, no join key.
+ *   - The base URL must already be an allowlisted https target; the OSC 8
+ *     renderer re-validates the host at render time regardless.
+ */
+import { getFunnelId } from './events.js';
+/**
+ * Server-side click-redirect endpoint. When set, promotional URLs route
+ * through here so the server can record a `promo_open` event + coarse
+ * geo (from CF-IPCountry / X-Appengine-Country) before 302ing to the
+ * real cognitum.one / agentics.org / etc. target.
+ */
+const CLICK_ENDPOINT_BASE = process.env.RUFLO_FUNNEL_CLICK_ENDPOINT ?? 'https://funnel.ruv.io/v1/click';
+/**
+ * Return `url` with UTM parameters appended, and — when telemetry consent is
+ * granted — a `fid` query parameter carrying the pseudonymous funnel ID.
+ * Preserves any query parameters the base URL already carried.
+ */
+export function attributionUrl(url, input) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    // Defense in depth: reject non-https schemes at the builder stage. The OSC 8
+    // renderer allowlist would drop them at render time too, but decorating a
+    // `javascript:` or `data:` URL with a valid-looking `fid` would still be a
+    // record we don't want to emit. Fail closed by returning the input verbatim.
+    if (parsed.protocol !== 'https:')
+        return url;
+    const params = parsed.searchParams;
+    params.set('utm_source', input.source ?? 'ruflo');
+    params.set('utm_medium', input.medium);
+    params.set('utm_campaign', input.campaign);
+    params.set('utm_content', input.content);
+    const fid = getFunnelId(input.now ?? new Date());
+    if (fid)
+        params.set('fid', fid);
+    return parsed.toString();
+}
+/**
+ * Wrap the target URL in a server-side click-redirect so the analytics
+ * function fires a `promo_open` event + records coarse geo before 302ing to
+ * the real destination.
+ *
+ * Only applied to promotional messages (they have a real URL destination).
+ * Disclosure/educational rows call attributionUrl directly.
+ *
+ * The click endpoint URL structure is:
+ *   https://funnel.ruv.io/v1/click/{messageId}?to=<utm-decorated-target>
+ *
+ * The server validates `to` against its own host allowlist, records the
+ * event, and 302s. If the click endpoint is unreachable at OSC 8 time,
+ * the browser falls back to the terminal's normal error page — but since
+ * this is a rare failure path and impressions are already recorded, the
+ * loss is bounded.
+ */
+export function clickTrackedUrl(messageId, targetUrl, input) {
+    const attributed = attributionUrl(targetUrl, input);
+    // If attribution rejected the URL (non-https, malformed), pass through
+    // verbatim — never smuggle a bad URL into the click endpoint.
+    if (attributed === targetUrl) {
+        try {
+            const p = new URL(targetUrl);
+            if (p.protocol !== 'https:')
+                return targetUrl;
+        }
+        catch {
+            return targetUrl;
+        }
+    }
+    // Sanitize the message id — allowlist [a-z0-9-] so a malformed id can't
+    // shape-shift the click endpoint path.
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(messageId))
+        return attributed;
+    const params = new URLSearchParams({ to: attributed });
+    return `${CLICK_ENDPOINT_BASE}/${encodeURIComponent(messageId)}?${params.toString()}`;
+}
+//# sourceMappingURL=attribution.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * 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 type { ConsentDomain, ConsentFile, ConsentReceipt } from './types.js';
+export declare const CONSENT_DOMAINS: ConsentDomain[];
+export declare function readConsents(): ConsentFile;
+export declare function getConsent(domain: ConsentDomain): ConsentReceipt;
+/**
+ * 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 declare function hasConsent(domain: ConsentDomain): boolean;
+export declare function recordConsent(domain: ConsentDomain, granted: boolean, surface: string, now?: Date): ConsentReceipt;
+export declare function revokeConsent(domain: ConsentDomain, surface: string): ConsentReceipt;
+//# sourceMappingURL=consent.d.ts.map

package/dist/src/funnel/consent.js

@@ -0,0 +1,58 @@
+/**
+ * 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',
+    'rev-share-payout',
+    'spinner-verbs',
+    'company-announcements',
+];
+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,47 @@
+/**
+ * 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;
+export declare function recordDisclosureAccepted(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