@claude-flow/cli 3.25.6 → 3.26.1

package/dist/src/commands/version.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `ruflo version` — ANV (Agent-Native Versioning) Phase 1.
+ * https://gist.github.com/ruvnet/0d858ad440a4439b4a2281a40c39b1a0
+ *
+ * Plain `ruflo --version` / `-V` (index.ts's showVersion()) is UNCHANGED —
+ * it stays bare semver so scripts parsing that output never see a surprise
+ * suffix. This is a separate subcommand: `ruflo version` prints the same
+ * bare semver by default, and `--explain` additionally renders the ANV
+ * catalog/benchmark breakdown when a catalog-manifest.json ships with this
+ * install. No catalog-manifest.json (e.g. an old install, or a dev checkout
+ * that hasn't run the generator) degrades to bare semver — the suffix is
+ * advisory, never load-bearing for npm range resolution or CLI behavior.
+ */
+import type { Command } from '../types.js';
+interface CatalogManifest {
+    schemaVersion: number;
+    generation: number;
+    generatedAt: string;
+    gitSha: string;
+    catalog: {
+        agents: number;
+        tools: number;
+        skills: number;
+    };
+    benchmark: {
+        tier: number;
+        verifiedAt: string;
+        signature?: string;
+    } | null;
+}
+/**
+ * The advisory suffix itself (semver build metadata, `+` prefix — legal per
+ * semver.org §10, ignored by npm for range resolution/precedence).
+ *   +ad.<release-sequence>.g<gitSha>.cat<generation>[.hal<tier>]
+ * `.hal<tier>` is only appended when a real, signed benchmark submission
+ * exists for THIS catalog generation — never fabricated (ANV's own
+ * "verifiable, no unverifiable claims" principle).
+ */
+export declare function buildAdvisorySuffix(manifest: CatalogManifest, releaseSequence?: number): string;
+export declare const versionCommand: Command;
+export {};
+//# sourceMappingURL=version.d.ts.map

package/dist/src/commands/version.js

@@ -0,0 +1,106 @@
+import { output } from '../output.js';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Locate catalog-manifest.json next to the installed package root. */
+function findCatalogManifest() {
+    const candidates = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        candidates.push(join(pkgRoot, 'catalog-manifest.json'));
+    }
+    catch { /* not resolvable via package resolution */ }
+    // Dev checkout fallback: this compiled file lives at dist/src/commands/version.js
+    // (three levels under the package root) when built, or is run via tsx one level
+    // shallower from src/commands/version.ts — try both.
+    candidates.push(join(__dirname, '..', '..', 'catalog-manifest.json'));
+    candidates.push(join(__dirname, '..', '..', '..', 'catalog-manifest.json'));
+    for (const c of candidates) {
+        if (!existsSync(c))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(c, 'utf-8'));
+            if (parsed && typeof parsed.generation === 'number' && parsed.catalog)
+                return parsed;
+        }
+        catch { /* corrupt manifest — treat as absent */ }
+    }
+    return null;
+}
+/**
+ * The advisory suffix itself (semver build metadata, `+` prefix — legal per
+ * semver.org §10, ignored by npm for range resolution/precedence).
+ *   +ad.<release-sequence>.g<gitSha>.cat<generation>[.hal<tier>]
+ * `.hal<tier>` is only appended when a real, signed benchmark submission
+ * exists for THIS catalog generation — never fabricated (ANV's own
+ * "verifiable, no unverifiable claims" principle).
+ */
+export function buildAdvisorySuffix(manifest, releaseSequence = 1) {
+    const parts = [`ad.${releaseSequence}`, `g${manifest.gitSha}`, `cat${manifest.generation}`];
+    if (manifest.benchmark)
+        parts.push(`hal${manifest.benchmark.tier}`);
+    return `+${parts.join('.')}`;
+}
+export const versionCommand = {
+    name: 'version',
+    description: 'Show installed version, with --explain for the ANV catalog breakdown',
+    options: [
+        {
+            name: 'explain',
+            description: 'Show the full ANV breakdown (catalog generation, counts, benchmark status)',
+            type: 'boolean',
+            default: false,
+        },
+        {
+            name: 'require-catalog-gte',
+            description: 'Exit non-zero unless the installed catalog generation is >= N (capability gating for scripts)',
+            type: 'number',
+        },
+    ],
+    examples: [
+        { command: 'ruflo version', description: 'Print the installed semver' },
+        { command: 'ruflo version --explain', description: 'Print the full ANV catalog/benchmark breakdown' },
+        { command: 'ruflo version --require-catalog-gte 40', description: 'Gate a script on a minimum catalog generation' },
+    ],
+    action: async (ctx) => {
+        const version = getInstalledCliVersion();
+        const manifest = findCatalogManifest();
+        const requireGte = ctx.flags.requireCatalogGte;
+        if (typeof requireGte === 'number') {
+            const generation = manifest?.generation ?? 0;
+            if (generation >= requireGte) {
+                output.writeln(`OK (installed catalog is ${generation})`);
+                return { success: true };
+            }
+            output.printError(`Installed catalog generation ${generation} is below required ${requireGte}`);
+            return { success: false };
+        }
+        if (!ctx.flags.explain) {
+            output.writeln(`${version}`);
+            return { success: true };
+        }
+        if (!manifest) {
+            output.writeln(`Installed: ruflo@${version}`);
+            output.writeln(output.dim('  (no catalog-manifest.json — plain semver, pre-ANV or dev checkout)'));
+            return { success: true };
+        }
+        const suffix = buildAdvisorySuffix(manifest);
+        output.writeln(`Installed: ${output.bold(`ruflo@${version}${suffix}`)}`);
+        output.writeln();
+        output.writeln(`Era:       AD (Agent Descent) — 1st generation`);
+        output.writeln(`Catalog:   generation ${manifest.generation} ` +
+            `(agents: ${manifest.catalog.agents} types, tools: ${manifest.catalog.tools} MCP, skills: ${manifest.catalog.skills})`);
+        if (manifest.benchmark) {
+            output.writeln(`Benchmark: GAIA tier ${manifest.benchmark.tier} (verified ${manifest.benchmark.verifiedAt.slice(0, 10)}, signed)`);
+        }
+        else {
+            output.writeln(output.dim('Benchmark: not yet submitted (no verified GAIA/HAL score for this catalog generation)'));
+        }
+        return { success: true };
+    },
+};
+//# sourceMappingURL=version.js.map

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,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