@claude-flow/cli 3.25.5 → 3.26.0

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

@@ -0,0 +1,19 @@
+/**
+ * `ruflo settings` — user-facing preferences router (ADR-311 amendment).
+ *
+ * The name change from `ruflo funnel …` is deliberate copy discipline:
+ * "funnel" is internal analytics terminology; it should not appear in the
+ * command surface end users see. Every subcommand here forwards to the
+ * existing `ruflo funnel` primitives so behavior stays identical — this
+ * is a friendlier wrapper, not a re-implementation.
+ *
+ * Subcommands:
+ *   ruflo settings                     Show effective settings + how to change them
+ *   ruflo settings notices status      Show whether the notices row is on
+ *   ruflo settings notices off         Turn off the notices row (persistent)
+ *   ruflo settings notices on          Re-enable the notices row
+ *   ruflo settings notices id          Show the pseudonymous notices id
+ */
+import type { Command } from '../types.js';
+export declare const settingsCommand: Command;
+//# sourceMappingURL=settings.d.ts.map

package/dist/src/commands/settings.js

@@ -0,0 +1,180 @@
+/**
+ * `ruflo settings` — user-facing preferences router (ADR-311 amendment).
+ *
+ * The name change from `ruflo funnel …` is deliberate copy discipline:
+ * "funnel" is internal analytics terminology; it should not appear in the
+ * command surface end users see. Every subcommand here forwards to the
+ * existing `ruflo funnel` primitives so behavior stays identical — this
+ * is a friendlier wrapper, not a re-implementation.
+ *
+ * Subcommands:
+ *   ruflo settings                     Show effective settings + how to change them
+ *   ruflo settings notices status      Show whether the notices row is on
+ *   ruflo settings notices off         Turn off the notices row (persistent)
+ *   ruflo settings notices on          Re-enable the notices row
+ *   ruflo settings notices id          Show the pseudonymous notices id
+ */
+import { output } from '../output.js';
+import { deleteFunnelData, funnelStateDir, getDisclosure, getFunnelId, hasConsent, readConsents, recordDisclosureDeclined, recordDisclosureReenabled, resolveFunnelEnabled, } from '../funnel/index.js';
+import { readStateJson, writeStateJson } from '../funnel/state.js';
+import { clearRateLimitStatus, markRateLimited, rateLimitNotice, readRateLimitStatus, } from '../funnel/rate-limit-notifier.js';
+import { clearQuotaLowStatus, markQuotaLow, quotaLowNotice, readQuotaLowStatus, } from '../funnel/power-saver-notifier.js';
+function setUserConfigEnabled(enabled) {
+    const cfg = readStateJson('funnel.json') ?? {};
+    cfg.enabled = enabled;
+    writeStateJson('funnel.json', cfg);
+}
+const noticesStatusSub = {
+    name: 'status',
+    description: 'Show whether notices are on and which source decided it',
+    action: async () => {
+        const decision = resolveFunnelEnabled();
+        const disclosure = getDisclosure();
+        output.writeln(`Notices: ${decision.enabled ? 'enabled' : 'disabled'} (decided by: ${decision.decidedBy})`);
+        output.writeln(`Disclosure: ${disclosure.state}`);
+        output.writeln(`Telemetry: ${hasConsent('telemetry') ? 'consent granted' : 'no consent'}`);
+        return { success: true, data: { decision, disclosure: disclosure.state } };
+    },
+};
+const noticesOffSub = {
+    name: 'off',
+    description: 'Turn off statusline notices (persistent, user-level)',
+    action: async () => {
+        setUserConfigEnabled(false);
+        recordDisclosureDeclined();
+        deleteFunnelData();
+        output.printSuccess('Notices disabled. Local notice data deleted.');
+        return { success: true };
+    },
+};
+const noticesOnSub = {
+    name: 'on',
+    description: 'Re-enable statusline notices',
+    action: async () => {
+        setUserConfigEnabled(true);
+        recordDisclosureReenabled();
+        const decision = resolveFunnelEnabled();
+        if (decision.enabled) {
+            output.printSuccess('Notices enabled.');
+        }
+        else {
+            output.printWarning(`User preference recorded, but notices stay off (decided by: ${decision.decidedBy})`);
+        }
+        return { success: true, data: decision };
+    },
+};
+const noticesIdSub = {
+    name: 'id',
+    description: 'Print the pseudonymous notices ID (telemetry consent required)',
+    action: async () => {
+        const id = getFunnelId();
+        output.writeln(id ?? '(no id — telemetry consent not granted, or notices are off)');
+        return { success: true, data: { id } };
+    },
+};
+const rateLimitedSub = {
+    name: 'rate-limited',
+    description: 'Manually flag that you have hit a Claude usage limit (ADR-312 Phase 0)',
+    options: [
+        { name: 'clear', description: 'Clear the flag', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        if (ctx.flags.clear) {
+            const changed = clearRateLimitStatus();
+            if (!changed) {
+                output.printError('Rate-limit flag was just toggled — try again in a few minutes (ADR-314 anti-abuse cooldown).');
+                return { success: false };
+            }
+            output.printSuccess('Rate-limit flag cleared.');
+            return { success: true };
+        }
+        const changed = markRateLimited();
+        if (!changed) {
+            output.printError('Rate-limit flag was just toggled — try again in a few minutes (ADR-314 anti-abuse cooldown).');
+            return { success: false };
+        }
+        output.printSuccess('Rate-limit flag set.');
+        output.writeln('');
+        output.writeln('This is a manual, self-reported flag — ruflo cannot detect Claude\'s');
+        output.writeln('usage-limit state automatically today (see ADR-312). While flagged,');
+        output.writeln('the notices row may suggest sponsored Cognitum capacity as a bridge');
+        output.writeln('until your own limit resets: ruflo proxy sponsor-enable');
+        output.writeln('');
+        output.writeln('Clear it any time: ruflo settings notices rate-limited --clear');
+        const notice = rateLimitNotice();
+        return { success: true, data: { notice, status: readRateLimitStatus() } };
+    },
+};
+const quotaLowSub = {
+    name: 'quota-low',
+    description: 'Manually flag that your Claude quota is running low (ADR-314 power saver)',
+    options: [
+        { name: 'clear', description: 'Clear the flag', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        if (ctx.flags.clear) {
+            const changed = clearQuotaLowStatus();
+            if (!changed) {
+                output.printError('Quota-low flag was just toggled — try again in a few minutes (ADR-314 anti-abuse cooldown).');
+                return { success: false };
+            }
+            output.printSuccess('Quota-low flag cleared.');
+            return { success: true };
+        }
+        const changed = markQuotaLow();
+        if (!changed) {
+            output.printError('Quota-low flag was just toggled — try again in a few minutes (ADR-314 anti-abuse cooldown).');
+            return { success: false };
+        }
+        output.printSuccess('Quota-low flag set.');
+        output.writeln('');
+        output.writeln('This is a manual, self-reported flag — ruflo cannot read your actual');
+        output.writeln('quota percentage today (see ADR-312/314). While flagged, and once you');
+        output.writeln('enable power saver mode, everyday requests route through Cognitum\'s');
+        output.writeln('own difficulty-based router (billed to your own Cognitum account):');
+        output.writeln('  ruflo proxy power-saver-enable');
+        output.writeln('');
+        output.writeln('Clear it any time: ruflo settings notices quota-low --clear');
+        const notice = quotaLowNotice();
+        return { success: true, data: { notice, status: readQuotaLowStatus() } };
+    },
+};
+const noticesCommand = {
+    name: 'notices',
+    description: 'Control the statusline notices row',
+    subcommands: [noticesStatusSub, noticesOffSub, noticesOnSub, noticesIdSub, rateLimitedSub, quotaLowSub],
+    action: noticesStatusSub.action,
+};
+const overviewAction = async () => {
+    const decision = resolveFunnelEnabled();
+    const disclosure = getDisclosure();
+    const consents = readConsents();
+    output.writeln('ruflo settings — user preferences');
+    output.writeln('');
+    output.writeln('Notices (statusline tips + product updates)');
+    output.writeln('  ruflo settings notices status    Show current state');
+    output.writeln('  ruflo settings notices off       Turn off all notices');
+    output.writeln('  ruflo settings notices on        Re-enable');
+    output.writeln('  ruflo settings notices id        Show pseudonymous notices id');
+    output.writeln('');
+    output.writeln(`  current: ${decision.enabled ? 'enabled' : 'disabled'} (${decision.decidedBy})`);
+    output.writeln(`  disclosure: ${disclosure.state}`);
+    const domains = Object.keys(consents);
+    if (domains.length) {
+        output.writeln(`  consents: ${domains.join(', ')}`);
+    }
+    output.writeln(`  state dir: ${funnelStateDir()}`);
+    return { success: true, data: { decision, disclosure: disclosure.state, consents } };
+};
+export const settingsCommand = {
+    name: 'settings',
+    description: 'View and change user preferences (notices, consents)',
+    subcommands: [noticesCommand],
+    examples: [
+        { command: 'ruflo settings', description: 'Overview + current state' },
+        { command: 'ruflo settings notices off', description: 'Turn off statusline notices' },
+        { command: 'ruflo settings notices status', description: 'Show current notices state' },
+    ],
+    action: overviewAction,
+};
+//# sourceMappingURL=settings.js.map

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