@claude-flow/cli 3.32.1 → 3.32.3

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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,92 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-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

@@ -1,101 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,88 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,74 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/**
- * 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