@claude-flow/cli 3.72.1 → 3.73.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.72.1",
+    "version": "3.73.0",
     "files": {
       "auto-memory-hook.mjs": "6078bd1c6b02dd3f80097f8d7f28904d48b3cdf7a534d2aa13966590694ca403",
       "hook-handler.cjs": "31db0f7492fbd8b2e48ea9adbc1ba293dfed1e006666d20e93ea76e158986947",
@@ -10,6 +10,6 @@
       "learning-loop.cjs": "d046cd6f8efb7dd40e1d2451516c181fc8b26477aefb1124c0df5f52a23f9190"
     }
   },
-  "signature": "xOPNAkZaRFxW1eLWGKMWxYTKSag+Q6LH2zEvMSKUkICLeNN5KDOOBmd9G6nqQqqj2W9Yj+iNPgo6fMvxM7KgAw==",
+  "signature": "JPs8pGUFfkmmIj+GpqM7snJ1AX9IJS8olXiwHgZjSTKCIcK0aERAd+Wjy3jfBbK1V8mqP+ZWeX8CRr4aA+3BDA==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -7,7 +7,7 @@
 <!-- Try Ruflo — the 3 badges first-time visitors actually act on -->
 [![npm version (ruflo)](https://img.shields.io/npm/v/ruflo?label=npx%20ruflo&style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/ruflo)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
+[![Star on GitHub](https://img.shields.io/github/stars/ruvnet/ruflo?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/ruflo)
 [![Follow @rUv on X](https://img.shields.io/badge/Follow-@rUv-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/rUv)
 
 <p align="center">
@@ -23,42 +23,49 @@
 
 <a id="start-here"></a>
 
-## <img src="docs/assets/readme/icons/terminal.svg" width="32" height="32" alt=""> Get started with Ruflo
+## <img src="docs/assets/readme/icons/terminal.svg" width="32" height="32" alt=""> Get started in one command
 
-<img src="docs/assets/readme/icons/plugins.svg" width="28" height="28" alt=""> **Start in Claude Code** with core tools, the visual console and runtime mods. Requires Claude Code **2.1.287 or later**. Run inside Claude Code:
+Run this in your project folder:
+
+```bash
+npx ruflo@latest init
+```
+
+Then open Claude Code in the same folder and give it a real task, for example:
 
 ```text
-/plugin marketplace add ruvnet/ruflo
-/plugin install ruflo-core@ruflo
-/plugin install ruflo-console@ruflo
-/plugin install ruflo-mods@ruflo
-/reload-plugins
-/ruflo
+Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.
 ```
 
-From a terminal on Claude Code 2.1.292 or later, one command adds the marketplace and installs a plugin: `claude plugin install ruflo-core@ruflo --marketplace ruvnet/ruflo`.
+`init` adds ruflo's agents, hooks, memory and MCP server to the project, and Claude Code picks them up on its next start. Codex and other MCP clients work too: point them at `npx -y ruflo@latest mcp start`.
 
-**Core** provides foundation tools. **Console** opens the agent cockpit. **Mods** add routing and policy enforcement inside Claude Code. Mods run with your account's permissions; review their code before installing.
+<p align="center"><img src="docs/assets/ruflo-console-tour.gif" width="720" alt="Looping recording of the ruflo console: overview, swarm view and missions in a sample project"></p>
 
-<img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> **Using Codex or another MCP enabled tool?** Use NPX for Ruflo project setup and connect your client to the Ruflo MCP server. Run the setup wizard in your project terminal:
+[First useful task, step by step](docs/ruflo-explained.md) · [User guide](docs/USERGUIDE.md) · [Compare install paths](#quick-start)
 
-```bash
-npx ruflo@latest init wizard
-```
+<details>
+<summary><b>Other ways to install</b> (Claude Code plugins only, MCP-only clients, terminal UI)</summary>
 
-For clients that support local stdio MCP servers, configure **command** `npx` and **arguments** `["-y", "ruflo@latest", "mcp", "start"]`. The equivalent server command is:
+**Claude Code plugins only.** This route installs core tools, the visual console and runtime mods, with no files added to your project. It needs Claude Code **2.1.287 or later**. Run inside Claude Code:
 
-```bash
-npx -y ruflo@latest mcp start
+```text
+/plugin marketplace add ruvnet/ruflo
+/plugin install ruflo-core@ruflo
+/plugin install ruflo-console@ruflo
+/plugin install ruflo-mods@ruflo
+/reload-plugins
+/ruflo
 ```
 
-MCP exposes Ruflo tools to your client. The console and mods above are Claude Code integrations; hook support depends on the client.
+From a terminal, on Claude Code 2.1.292 or later: `claude plugin install ruflo-core@ruflo --marketplace ruvnet/ruflo`. Mods run with your account's permissions, so review their code before installing.
+
+**Codex or another MCP client, without project setup.** Configure the **command** `npx` with the **arguments** `["-y", "ruflo@latest", "mcp", "start"]`. To set up a project interactively, run `npx ruflo@latest init wizard`.
 
-<img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> **Prefer a plain terminal? Optional.** The console also runs on its own, with no Claude Code: `npx ruflo tui` (add `--plain` to print one frame for scripts). It shows Overview, Cost, Swarm, Events and Missions, plus an optional AI page. [Terminal UI guide](docs/USERGUIDE.md#terminal-ui-optional)
+**Plain terminal.** The console also runs on its own, without Claude Code: `npx ruflo tui`. Add `--plain` to print one frame for scripts. See the [terminal UI guide](docs/USERGUIDE.md#terminal-ui-optional).
 
 <p align="center"><img src="docs/assets/ruflo-tui-compact.svg" width="640" alt="Looping recording of the optional ruflo terminal UI with its pictures: Overview in the Classic BBS look, the Orbital look with its moving globe, and the Swarm graph, in a sample project"></p>
 
-[Compare install paths](#quick-start) · [Open the console](#console-walkthrough) · [User guide](docs/USERGUIDE.md)
+</details>
 
 <div align="center">
 
@@ -484,6 +491,7 @@ Four docs for four audiences:
 |-----|-----------------|
 | **[Status](docs/STATUS.md)** | See what currently works — capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
 | **[User Guide](docs/USERGUIDE.md)** | Daily reference — every command, every config flag, every plugin. The *how-do-I* doc. |
+| **[Compare frameworks](docs/compare.md)** | Deciding between Ruflo, Claude Code built-in agents, CrewAI, LangGraph, or AutoGen. The *which-one-for-me* doc. |
 | **[MetaHarness Guide](docs/metaharness-user-guide.md)** | How to grade your agent setup, scan tool configs for security, detect changes between runs, and eject a project into a standalone agent toolkit. The *audit-my-setup* doc. |
 | **[Benchmarks](https://gist.github.com/ruvnet/298f8c668c8859b369f91734a0e9cbbe)** | v3.8.0 SOTA matrix vs LangGraph / AutoGen / CrewAI on darwin-arm64 + linux-x64. ruflo wins cold start, single turn, RSS by 1.3×–1953×. The *is-it-fast* doc. |
 | **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness — `ruflo verify`. The *trust-but-verify* doc. |

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-11-06T02:50:18.000Z",
-  "gitSha": "29b327ee",
+  "generatedAt": "2026-11-09T01:20:38.869Z",
+  "gitSha": "a8b3304b",
   "catalog": {
     "agents": 177,
     "tools": 451,

package/dist/src/commands/agent.js

@@ -9,6 +9,7 @@ import { wasmSubcommands } from './agent-wasm.js';
 import { agentPublishCommand } from './agntcy/publish.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { noteFirstAgentRun } from '../funnel/activation.js';
 /**
  * Update swarm-activity.json metrics after agent count changes.
  * The statusline reads this file to display the swarm agent count.
@@ -172,6 +173,7 @@ const spawnCommand = {
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
             }
+            noteFirstAgentRun('cli'); // activation funnel (opt-in; no-op without telemetry consent)
             return { success: true, data: result };
         }
         catch (error) {

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

@@ -11,6 +11,7 @@
  *   funnel earnings   show accrued and paid revenue-share balance
  *   funnel unenroll   revoke local enrollment (funnel itself stays enabled)
  *   funnel id         print the pseudonymous funnel ID, if one exists
+ *   funnel telemetry  opt in or out of anonymous usage telemetry (on | off | status)
  */
 import type { Command } from '../types.js';
 export declare const funnelCommand: Command;

package/dist/src/commands/funnel.js

@@ -11,6 +11,7 @@
  *   funnel earnings   show accrued and paid revenue-share balance
  *   funnel unenroll   revoke local enrollment (funnel itself stays enabled)
  *   funnel id         print the pseudonymous funnel ID, if one exists
+ *   funnel telemetry  opt in or out of anonymous usage telemetry (on | off | status)
  */
 import { execFile } from 'node:child_process';
 import * as fs from 'node:fs';
@@ -63,11 +64,45 @@ const disableSub = {
     action: async () => {
         setUserConfigEnabled(false);
         recordDisclosureDeclined();
+        // "All surfaces" includes opt-in event telemetry: revoke it too.
+        if (hasConsent('telemetry'))
+            recordConsent('telemetry', false, 'cli-funnel-disable');
         deleteFunnelData(); // opt-out deletes the pseudonymous ID + local event queue
-        output.printSuccess('Funnel disabled. All promotional surfaces are off; local funnel data deleted.');
+        output.printSuccess('Funnel disabled. All promotional surfaces are off, no funnel.ruv.io requests are made, and local funnel data is deleted.');
         return { success: true };
     },
 };
+// ADR-302 consent domain `telemetry` (ADR-305/309): explicit opt-in to the
+// anonymous funnel event stream. Enrollment never toggles it; only this
+// command does. Off by default.
+const telemetrySub = {
+    name: 'telemetry',
+    description: 'Opt in or out of anonymous usage telemetry: telemetry on | off | status',
+    action: async (ctx) => {
+        const verb = String(ctx.args[0] ?? 'status').toLowerCase();
+        if (verb === 'on') {
+            recordConsent('telemetry', true, 'cli-funnel-telemetry');
+            const id = getFunnelId();
+            output.printSuccess('Telemetry on. Once per session ruflo sends anonymous funnel events (daily-bucketed, no paths, prompts, code or account data) with a random ID that rotates every 90 days.');
+            output.writeln('Turn it off any time with `ruflo funnel telemetry off`; that also deletes the ID and the local event queue.');
+            return { success: true, data: { telemetry: true, id } };
+        }
+        if (verb === 'off') {
+            recordConsent('telemetry', false, 'cli-funnel-telemetry');
+            deleteFunnelData();
+            output.printSuccess('Telemetry off. The pseudonymous ID and the local event queue are deleted.');
+            return { success: true, data: { telemetry: false } };
+        }
+        if (verb !== 'status') {
+            output.printError(`Unknown telemetry option "${verb}". Use: on | off | status`);
+            return { success: false, exitCode: 1 };
+        }
+        const on = hasConsent('telemetry');
+        output.writeln(`Telemetry: ${on ? 'on (opted in)' : 'off'}`);
+        output.writeln('Without opting in, ruflo makes one anonymous request per session to fetch tips (release + OS only); `ruflo funnel disable` stops that too.');
+        return { success: true, data: { telemetry: on } };
+    },
+};
 const enableSub = {
     name: 'enable',
     description: 'Re-enable funnel surfaces at the user tier (env/enterprise disables still win)',
@@ -287,7 +322,7 @@ const idSub = {
 export const funnelCommand = {
     name: 'funnel',
     description: 'Control the Cognitum lifecycle funnel surfaces (tips, enrollment, notices)',
-    subcommands: [statusSub, disableSub, enableSub, acceptSub, openSub, enrollSub, earningsSub, unenrollSub, idSub],
+    subcommands: [statusSub, disableSub, enableSub, acceptSub, openSub, enrollSub, earningsSub, unenrollSub, idSub, telemetrySub],
     examples: [
         { command: 'ruflo funnel status', description: 'Effective state + deciding source' },
         { command: 'ruflo funnel accept', description: 'Skip the 24h grace so rotation starts now' },

package/dist/src/commands/hooks.js

@@ -4612,8 +4612,22 @@ const refreshFunnelCommand = {
     ],
     action: async (ctx) => {
         try {
-            const { refreshRemoteMessages } = await import('../funnel/index.js');
-            const result = await refreshRemoteMessages();
+            const { refreshRemoteMessages, resolveFunnelEnabled, hasConsent, flushEvents } = await import('../funnel/index.js');
+            // `ruflo funnel disable` (and every other opt-out source) must stop the
+            // network call, not only the promo row (ADR-309 operational telemetry).
+            const decision = resolveFunnelEnabled();
+            const result = decision.enabled
+                ? await refreshRemoteMessages()
+                : { refreshed: false, skipped: 'funnel-disabled', decidedBy: decision.decidedBy };
+            // Opt-in event telemetry (ADR-305/309): only with an explicit, current
+            // telemetry consent receipt; flushEvents re-checks consent itself.
+            if (decision.enabled && hasConsent('telemetry')) {
+                const { rufloPackageVersion } = await import('../mcp-protocol.js');
+                // Activation funnel: one "active today" marker per day (7-day retention).
+                const { recordSessionActive } = await import('../funnel/activation.js');
+                recordSessionActive(rufloPackageVersion());
+                result.events = await flushEvents({ release: rufloPackageVersion() });
+            }
             if (!ctx.flags.quiet) {
                 output.writeln(JSON.stringify(result));
             }

package/dist/src/commands/init.js

@@ -79,6 +79,45 @@ async function offerCapabilityEnrollment(ctx) {
         // Enrollment is optional; init success is never affected.
     }
 }
+/**
+ * One-time opt-in to anonymous usage telemetry (ADR-302 telemetry domain,
+ * ADR-309). Separate from enrollment, which must never toggle telemetry.
+ * Interactive TTY only, never in CI, skipped with --no-telemetry-prompt,
+ * asked once whatever the answer, default No. Never affects init success.
+ */
+async function offerTelemetryOptIn(ctx) {
+    try {
+        if (ctx.flags.format === 'json')
+            return;
+        const noPrompt = Boolean(ctx.flags['no-telemetry-prompt'] || ctx.flags.noTelemetryPrompt || ctx.flags.telemetryPrompt === false);
+        const { shouldOfferTelemetry } = await import('../funnel/activation.js');
+        if (!shouldOfferTelemetry({ noTelemetryPrompt: noPrompt, cwd: ctx.cwd }))
+            return;
+        output.writeln();
+        output.writeln('Help improve ruflo? Opting in sends anonymous usage events: init finished, first agent run, active days.');
+        output.writeln(output.dim('  Daily-bucketed, with a random ID that rotates every 90 days. No code, paths, prompts or account data.'));
+        const accepted = await confirm({ message: 'Share anonymous usage telemetry?', default: false });
+        const { recordConsent } = await import('../funnel/index.js');
+        recordConsent('telemetry', Boolean(accepted), 'init-prompt');
+        output.writeln(output.dim(accepted
+            ? '  Thanks. Turn it off any time with \`ruflo funnel telemetry off\`.'
+            : '  Telemetry stays off. Turn it on later with \`ruflo funnel telemetry on\`.'));
+    }
+    catch {
+        // Optional; init success is never affected.
+    }
+}
+/** Activation funnel: no-op without telemetry consent; never throws. */
+async function noteInitCompleted() {
+    try {
+        const [{ recordInitCompleted }, { rufloPackageVersion }] = await Promise.all([
+            import('../funnel/activation.js'),
+            import('../mcp-protocol.js'),
+        ]);
+        recordInitCompleted(rufloPackageVersion());
+    }
+    catch { /* optional */ }
+}
 async function resolveCodexInitializer(cwd) {
     // Use a variable to prevent TypeScript from statically resolving the optional module
     const codexModuleId = '@claude-flow/codex';
@@ -937,26 +976,33 @@ const initClaudeAction = async (ctx) => {
                 output.writeln(output.warning(`  ruflo mods not enabled: ${err instanceof Error ? err.message : String(err)}`));
             }
         }
-        if (!startDaemon && !startAll) {
-            const bin = (process.argv[1] || '').includes('ruflo') ? 'ruflo' : 'claude-flow';
-            output.writeln(output.bold('Next steps:'));
-            output.printList([
-                `Run ${output.highlight(`${bin} daemon start`)} to start background workers`,
-                // Memory is initialized automatically during init (persistent by
-                // default — see executor.ts) — no separate `memory init` step needed
-                // unless the DB was skipped (MINIMAL_INIT_OPTIONS) or needs --force.
-                `Run ${output.highlight(`${bin} swarm init`)} to initialize a swarm`,
-                `Or use ${output.highlight(`${bin} init --start-all`)} to do all of the above`,
-                options.components.settings ? `Review ${output.highlight('.claude/settings.json')} for hook configurations` : '',
-                // ADR-150 — surface the new metaharness scorecard to every new user.
-                // Optional dep; the command degrades gracefully when not installed.
-                `Run ${output.highlight(`${bin} metaharness score`)} for a 5-dim harness readiness scorecard (ADR-150)`,
-            ].filter(Boolean));
-        }
         if (ctx.flags.format === 'json') {
             output.printJson(result);
         }
         await offerCapabilityEnrollment(ctx);
+        await offerTelemetryOptIn(ctx);
+        await noteInitCompleted();
+        if (!startDaemon && !startAll && ctx.flags.format !== 'json') {
+            // End on something about the user's own repo, not a list of commands
+            // (adoption plan item 1). Printed after the optional prompts so it is
+            // the last thing on screen. Local-only, time-capped, never throws.
+            const { snapshotProject, snapshotLines, firstPrompt } = await import('../init/first-win.js');
+            const snap = snapshotProject(ctx.cwd);
+            const lines = snapshotLines(snap);
+            output.writeln();
+            if (lines.length) {
+                output.writeln(output.bold('Your project:'));
+                output.printList(lines);
+                output.writeln();
+            }
+            output.writeln(output.bold('Try it — open Claude Code here and paste:'));
+            output.writeln(`  ${output.highlight(firstPrompt(snap))}`);
+            output.writeln();
+            const bin = (process.argv[1] || '').includes('ruflo') ? 'ruflo' : 'claude-flow';
+            output.writeln(output.dim(`Background workers: ${bin} daemon start · health check: ${bin} doctor`));
+            // ADR-150: surface the metaharness scorecard (optional dep; degrades gracefully when absent).
+            output.writeln(output.dim(`Harness readiness: ${bin} metaharness score (5-dim scorecard)`));
+        }
         return { success: true, data: result };
     }
     catch (error) {
@@ -1298,6 +1344,8 @@ const wizardCommand = {
                 ],
             });
             await offerCapabilityEnrollment(ctx);
+            await offerTelemetryOptIn(ctx);
+            await noteInitCompleted();
             return { success: true, data: result };
         }
         catch (error) {
@@ -1714,6 +1762,12 @@ export const initCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            name: 'no-telemetry-prompt',
+            description: 'Skip the one-time question about anonymous usage telemetry (default answer is No)',
+            type: 'boolean',
+            default: false,
+        },
         {
             name: 'only-claude',
             description: 'Only create .claude/ directory (skip runtime)',

package/dist/src/commands/mcp.js

@@ -276,6 +276,21 @@ const startCommand = {
             });
             // Start the server
             const status = await manager.start();
+            // Plugin-user visibility (ADR-309 operational telemetry): plugin-only
+            // users never run `init`, so no SessionStart hook ever refreshes the
+            // funnel cache for them. When the ruflo-core plugin launched us, make
+            // the same 6h-cached /v1/messages fetch, honouring every opt-out. Off
+            // the start path, never awaited, and silent: stdout is the MCP channel.
+            if (transport === 'stdio') {
+                void (async () => {
+                    try {
+                        const { launchSurface, resolveFunnelEnabled, refreshRemoteMessages } = await import('../funnel/index.js');
+                        if (launchSurface() && resolveFunnelEnabled().enabled)
+                            await refreshRemoteMessages();
+                    }
+                    catch { /* best-effort */ }
+                })();
+            }
             // #2234 — exit cleanly if Claude Code (our parent) exits and we get
             // reparented to launchd/init (ppid === 1). Otherwise the node stdio
             // server lingers as an orphan, accumulating ~50 MB per restart, and an

package/dist/src/commands/neural.js

@@ -1526,7 +1526,9 @@ const benchmarkCommand = {
                 // when it isn't installed — install-safety / Build V3 pattern from #2586).
                 const attentionPkg = '@ruvector/attention';
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic import of optional native WASM module with no type declarations
-                const attention = await import(attentionPkg);
+                // @ruvector/attention is CommonJS: under import() its classes sit on `default`.
+                const attentionMod = await import(attentionPkg);
+                const attention = (attentionMod.default ?? attentionMod);
                 // Manual benchmark since benchmarkAttention has a binding bug
                 const benchmarkMechanism = async (name, mechanism) => {
                     const query = new Float32Array(dim);
@@ -1546,10 +1548,10 @@ const benchmarkCommand = {
                     }
                     // Warmup
                     for (let i = 0; i < 10; i++)
-                        mechanism.computeRaw(query, keys, values);
+                        mechanism.compute(query, keys, values);
                     const start = performance.now();
                     for (let i = 0; i < iterations; i++) {
-                        mechanism.computeRaw(query, keys, values);
+                        mechanism.compute(query, keys, values);
                     }
                     const elapsed = performance.now() - start;
                     return {

package/dist/src/commands/swarm.js

@@ -8,6 +8,7 @@ import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { swarmJoinCommand } from './agntcy/swarm-join.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { noteFirstAgentRun } from '../funnel/activation.js';
 // Read the CLI-side swarm state file (`.swarm/state.json`), written by
 // `swarm init` and rewritten by `swarm start` / `swarm stop`.
 function readLocalSwarmState() {
@@ -566,6 +567,7 @@ const initCommand = {
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
             }
+            noteFirstAgentRun('cli'); // activation funnel (opt-in; no-op without telemetry consent)
             return { success: true, data: result };
         }
         catch (error) {

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

@@ -0,0 +1,30 @@
+/**
+ * Activation funnel (ruflo adoption plan; ADR-309 opt-in telemetry).
+ *
+ *   installed  -> init_completed -> first_agent_run -> session_active (7-day retention)
+ *
+ * Every event goes through recordFunnelEvent, which records nothing without
+ * an explicit, current `telemetry` consent receipt. The once-ever and
+ * once-per-day markers live in their own state file because a successful
+ * flush removes sent events from the queue (lastRecordedEvent would forget).
+ */
+import type { FunnelSurface } from './types.js';
+/** `ruflo init` finished in a project. Recorded on every successful init. */
+export declare function recordInitCompleted(release: string, now?: Date): boolean;
+/** The first agent spawn or swarm init on this machine. Recorded once, ever. */
+export declare function recordFirstAgentRun(release: string, surface?: FunnelSurface, now?: Date): boolean;
+/** At most one "active today" marker per calendar day (UTC). */
+export declare function recordSessionActive(release: string, now?: Date): boolean;
+/**
+ * Whether `ruflo init` should ask the one-time telemetry question: an
+ * interactive terminal, not CI, funnel not disabled, no telemetry receipt
+ * yet (asked once, whatever the answer), and not suppressed by flag.
+ */
+export declare function shouldOfferTelemetry(opts?: {
+    noTelemetryPrompt?: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+/** Fire-and-forget wrapper for command handlers: never throws, never blocks. */
+export declare function noteFirstAgentRun(surface?: FunnelSurface): void;
+//# sourceMappingURL=activation.d.ts.map

package/dist/src/funnel/activation.js

@@ -0,0 +1,69 @@
+/**
+ * Activation funnel (ruflo adoption plan; ADR-309 opt-in telemetry).
+ *
+ *   installed  -> init_completed -> first_agent_run -> session_active (7-day retention)
+ *
+ * Every event goes through recordFunnelEvent, which records nothing without
+ * an explicit, current `telemetry` consent receipt. The once-ever and
+ * once-per-day markers live in their own state file because a successful
+ * flush removes sent events from the queue (lastRecordedEvent would forget).
+ */
+import { getConsent } from './consent.js';
+import { recordFunnelEvent } from './events.js';
+import { isCI, isInteractive } from './environment.js';
+import { resolveFunnelEnabled } from './precedence.js';
+import { readStateJson, writeStateJson } from './state.js';
+const MARKERS_FILE = 'funnel-activation.json';
+const day = (now) => now.toISOString().slice(0, 10);
+function markers() {
+    return readStateJson(MARKERS_FILE) ?? {};
+}
+/** `ruflo init` finished in a project. Recorded on every successful init. */
+export function recordInitCompleted(release, now = new Date()) {
+    return recordFunnelEvent('init_completed', 'init', release, now);
+}
+/** The first agent spawn or swarm init on this machine. Recorded once, ever. */
+export function recordFirstAgentRun(release, surface = 'cli', now = new Date()) {
+    const m = markers();
+    if (m.firstAgentRunAt)
+        return false;
+    if (!recordFunnelEvent('first_agent_run', surface, release, now))
+        return false;
+    writeStateJson(MARKERS_FILE, { ...m, firstAgentRunAt: now.toISOString() });
+    return true;
+}
+/** At most one "active today" marker per calendar day (UTC). */
+export function recordSessionActive(release, now = new Date()) {
+    const m = markers();
+    const today = day(now);
+    if (m.lastActiveDay === today)
+        return false;
+    if (!recordFunnelEvent('session_active', 'cli', release, now))
+        return false;
+    writeStateJson(MARKERS_FILE, { ...m, lastActiveDay: today });
+    return true;
+}
+/**
+ * Whether `ruflo init` should ask the one-time telemetry question: an
+ * interactive terminal, not CI, funnel not disabled, no telemetry receipt
+ * yet (asked once, whatever the answer), and not suppressed by flag.
+ */
+export function shouldOfferTelemetry(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.noTelemetryPrompt)
+        return false;
+    if (isCI(env))
+        return false;
+    if (!isInteractive())
+        return false;
+    if (!resolveFunnelEnabled(opts.cwd ?? process.cwd(), env).enabled)
+        return false;
+    return getConsent('telemetry').at === null;
+}
+/** Fire-and-forget wrapper for command handlers: never throws, never blocks. */
+export function noteFirstAgentRun(surface = 'cli') {
+    void import('../mcp-protocol.js')
+        .then(({ rufloPackageVersion }) => { recordFirstAgentRun(rufloPackageVersion(), surface); })
+        .catch(() => undefined);
+}
+//# sourceMappingURL=activation.js.map

package/dist/src/funnel/events.js

@@ -39,8 +39,11 @@ const EVENT_NAMES = [
     'training_share_disabled',
     'advisor_tip_enabled',
     'advisor_tip_disabled',
+    'init_completed',
+    'first_agent_run',
+    'session_active',
 ];
-const SURFACES = ['statusline', 'init', 'credit_exhaustion'];
+const SURFACES = ['statusline', 'init', 'credit_exhaustion', 'cli'];
 /** Rotate the pseudonymous ID every 90 days (ADR-305). */
 const FUNNEL_ID_TTL_MS = 90 * 24 * 60 * 60 * 1000;
 /**

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

@@ -9,7 +9,8 @@ export { resolveFunnelEnabled } from './precedence.js';
 export { CONSENT_DOMAINS, getConsent, hasConsent, readConsents, recordConsent, revokeConsent, } from './consent.js';
 export { DISCLOSURE_GRACE_MS, DISCLOSURE_ROTATION_SLOT_MS, getDisclosure, promoEligible, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
 export { MAX_MESSAGE_COLUMNS, MESSAGES, containsForbiddenSequences, displayWidth, eligibleMessages, eligibleMessagesFromPools, isAllowedUrl, isValidMessage, } from './messages.js';
-export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, refreshRemoteMessages, } from './message-transport.js';
+export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, funnelUserAgent, launchSurface, refreshRemoteMessages, } from './message-transport.js';
+export { flushEvents } from './event-transport.js';
 export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage, } from './rotation.js';
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, type CreditPromptSession, type ProviderErrorLike, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';

package/dist/src/funnel/index.js

@@ -9,7 +9,8 @@ export { resolveFunnelEnabled } from './precedence.js';
 export { CONSENT_DOMAINS, getConsent, hasConsent, readConsents, recordConsent, revokeConsent, } from './consent.js';
 export { DISCLOSURE_GRACE_MS, DISCLOSURE_ROTATION_SLOT_MS, getDisclosure, promoEligible, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
 export { MAX_MESSAGE_COLUMNS, MESSAGES, containsForbiddenSequences, displayWidth, eligibleMessages, eligibleMessagesFromPools, isAllowedUrl, isValidMessage, } from './messages.js';
-export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, refreshRemoteMessages, } from './message-transport.js';
+export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, funnelUserAgent, launchSurface, refreshRemoteMessages, } from './message-transport.js';
+export { flushEvents } from './event-transport.js';
 export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage, } from './rotation.js';
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';

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

@@ -31,6 +31,18 @@
  *      the trust boundary. All content is treated as untrusted regardless.
  */
 import type { FunnelMessage } from './types.js';
+/**
+ * User-Agent for the messages fetch — ADR-309 operational telemetry (see
+ * docs/privacy/funnel-legitimate-interest-assessment.md). Only the CLI
+ * release and the coarse OS/CPU family, so the server can count releases
+ * and platforms. No identifier, path, hostname, or account: the
+ * `ruflo-funnel/messages` prefix stays first so existing log filters match.
+ * A trailing `surface/plugin` marks a fetch made by the ruflo-core plugin's
+ * MCP launch, so plugin-only users (who never run `init`) can be counted.
+ */
+export declare function funnelUserAgent(version?: string, platform?: string, arch?: string, surface?: string | undefined): string;
+/** The surface set by a launcher (plugins/ruflo-core/scripts/mcp-launch.cjs), if any. */
+export declare function launchSurface(env?: NodeJS.ProcessEnv): string | undefined;
 /** Endpoint the client hits — overridable for staging / self-hosted. */
 export declare const DEFAULT_MESSAGES_ENDPOINT: string;
 /**

package/dist/src/funnel/message-transport.js

@@ -34,7 +34,29 @@ import * as https from 'https';
 import { URL as NodeUrl } from 'url';
 import { isValidMessage } from './messages.js';
 import { readStateJson, writeStateJson } from './state.js';
+import { rufloPackageVersion } from '../mcp-protocol.js';
 const CACHE_FILE = 'funnel-messages-cache.json';
+/**
+ * User-Agent for the messages fetch — ADR-309 operational telemetry (see
+ * docs/privacy/funnel-legitimate-interest-assessment.md). Only the CLI
+ * release and the coarse OS/CPU family, so the server can count releases
+ * and platforms. No identifier, path, hostname, or account: the
+ * `ruflo-funnel/messages` prefix stays first so existing log filters match.
+ * A trailing `surface/plugin` marks a fetch made by the ruflo-core plugin's
+ * MCP launch, so plugin-only users (who never run `init`) can be counted.
+ */
+export function funnelUserAgent(version = rufloPackageVersion(), platform = process.platform, arch = process.arch, surface = launchSurface()) {
+    const clean = (v) => v.replace(/[^A-Za-z0-9._-]/g, '').slice(0, 32) || 'unknown';
+    const tail = surface ? ` surface/${surface}` : '';
+    return `ruflo-funnel/messages ruflo/${clean(version)} (${clean(platform)}; ${clean(arch)})${tail}`;
+}
+/** Launch surfaces the UA may name. Closed set: an env value outside it is dropped. */
+const LAUNCH_SURFACES = new Set(['plugin']);
+/** The surface set by a launcher (plugins/ruflo-core/scripts/mcp-launch.cjs), if any. */
+export function launchSurface(env = process.env) {
+    const v = env.RUFLO_LAUNCH_SURFACE;
+    return v && LAUNCH_SURFACES.has(v) ? v : undefined;
+}
 const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h — matches server Cache-Control
 const CACHE_MAX_BYTES = 128 * 1024;
 const CACHE_MAX_MESSAGES = 200;
@@ -79,7 +101,7 @@ function httpsGet(url) {
             path: target.pathname + target.search,
             method: 'GET',
             headers: {
-                'User-Agent': 'ruflo-funnel/messages',
+                'User-Agent': funnelUserAgent(),
                 'Accept': 'application/json',
             },
         }, (res) => {

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

@@ -77,8 +77,8 @@ export interface NormalizedCreditError {
     /** Original provider error, preserved verbatim for --verbose paths. */
     cause?: unknown;
 }
-export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled';
-export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion';
+export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled' | 'init_completed' | 'first_agent_run' | 'session_active';
+export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion' | 'cli';
 export interface FunnelEvent {
     schemaVersion: 1;
     event: FunnelEventName;