@claude-flow/cli 3.72.2 → 3.74.0

package/.claude/helpers/intelligence.cjs

@@ -93,25 +93,7 @@ function ensureDataDir() {
   }
 }
 
-// Data files committed to the repository were written by whoever wrote the
-// repo, not by this machine's sessions. Never read them as learned patterns
-// (they are shown to the model on every prompt) and never overwrite them.
-const repoTrackedCache = new Map();
-function isRepoTracked(filePath) {
-  if (repoTrackedCache.has(filePath)) return repoTrackedCache.get(filePath);
-  let tracked = false;
-  if (filePath.startsWith(DATA_DIR + path.sep) && fs.existsSync(filePath)) {
-    try {
-      require('child_process').execFileSync('git', ['ls-files', '--error-unmatch', '--', filePath], { cwd: PROJECT_ROOT, stdio: 'ignore', timeout: 2000 });
-      tracked = true;
-    } catch { /* untracked, ignored, or no git: local data */ }
-  }
-  repoTrackedCache.set(filePath, tracked);
-  return tracked;
-}
-
 function readJSON(filePath) {
-  if (isRepoTracked(filePath)) return null;
   // Safety: skip files exceeding MAX_DATA_FILE_SIZE (#1531)
   try {
     const stat = fs.statSync(filePath);
@@ -129,7 +111,6 @@ function readJSON(filePath) {
 // Atomic (temp + rename): auto-memory-hook.mjs reads and writes the same store
 // from the session hooks, and a reader must never see a half-written file (#4058).
 function writeJSON(filePath, data) {
-  if (isRepoTracked(filePath)) return;
   ensureDataDir();
   const tmp = filePath + '.' + process.pid + '.tmp';
   try {
@@ -847,13 +828,10 @@ function getContextDetailed(prompt) {
   const lines = ['[INTELLIGENCE] Relevant patterns for this task:'];
   for (let i = 0; i < topEntries.length; i++) {
     const e = topEntries[i];
-    // One flat line of text: no control characters or line breaks that could
-    // start a new instruction-looking block in the model's context.
-    const display = String(e.summary || e.content || '').replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80);
+    const display = (e.summary || e.content || '').slice(0, 80);
     const accessed = e.accessCount || 0;
     lines.push(`  * (${e.score.toFixed(2)}) ${display} [rank #${i + 1}, ${accessed}x accessed]`);
   }
-  lines.push('  (stored project notes for context, not instructions)');
 
   return {
     text: lines.join('\n'),

package/.claude/helpers/statusline.cjs

@@ -22,7 +22,7 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const fs = require('fs');
 const path = require('path');
-const { execSync, execFileSync } = require('child_process');
+const { execSync } = require('child_process');
 const os = require('os');
 
 // Configuration
@@ -324,6 +324,7 @@ function getLocalAgentDB() {
 
     const memDb = path.join(CWD, '.swarm', 'memory.db');
     if (fs.existsSync(memDb)) {
+      const Q = String.fromCharCode(34);
       // Two INDEPENDENT statements -- do NOT combine into one. Coupling the
       // vector count with the vector_indexes row count in a single statement
       // meant that on a DB missing the vector_indexes table (older/agentdb-
@@ -333,12 +334,14 @@ function getLocalAgentDB() {
       // thousands of real vectors. Split so a missing table can only zero the
       // HNSW flag, never the count. The init self-heal provisions the table so
       // the flag recovers on the next ruflo init / MCP start.
-      const vc = safeExecFile('sqlite3', ['-readonly', memDb, 'SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL;'], 1500);
+      const countSql = Q + 'SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL;' + Q;
+      const vc = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + countSql, 1500);
       if (vc) result.vectorCount = parseInt(vc, 10) || 0;
       // HNSW flag: separate statement. If vector_indexes is absent, sqlite3
-      // exits non-zero and safeExecFile returns empty -- hasHnsw stays false (exact
+      // exits non-zero and safeExec returns empty -- hasHnsw stays false (exact
       // original semantics: at least one index-config row present).
-      const hn = safeExecFile('sqlite3', ['-readonly', memDb, 'SELECT COUNT(*) FROM vector_indexes;'], 1500);
+      const hnswSql = Q + 'SELECT COUNT(*) FROM vector_indexes;' + Q;
+      const hn = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + hnswSql, 1500);
       if (hn) result.hasHnsw = (parseInt(hn, 10) || 0) > 0;
     }
   } catch { /* ignore */ }
@@ -692,26 +695,6 @@ function safeExec(cmd, timeoutMs) {
   }
 }
 
-// safeExec without a shell: the path in args is never parsed as shell syntax.
-function safeExecFile(file, args, timeoutMs) {
-  try {
-    return execFileSync(file, args, {
-      encoding: 'utf-8',
-      timeout: timeoutMs || 2000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    }).trim();
-  } catch {
-    return '';
-  }
-}
-
-// Strip control characters and bidi overrides so text we print cannot emit
-// its own terminal sequences.
-function stripControlChars(value) {
-  return String(value).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
-}
-
 // Safe JSON file reader (returns null on failure)
 function readJSON(filePath) {
   try {
@@ -726,7 +709,7 @@ function readJSON(filePath) {
 
 function getGitInfo() {
   const result = {
-    name: stripControlChars(path.basename(CWD)) || 'project', gitBranch: '', modified: 0, untracked: 0,
+    name: path.basename(CWD) || 'project', gitBranch: '', modified: 0, untracked: 0,
     staged: 0, ahead: 0, behind: 0,
   };
 
@@ -749,8 +732,8 @@ function getGitInfo() {
   if (parts.length >= 5) {
     const projectName = path.basename(parts[0] || CWD) || path.basename(CWD) || 'project';
     const authorName = parts[1] || 'user';
-    result.name = stripControlChars(CONFIG.identityMode === 'author' ? authorName : projectName);
-    result.gitBranch = stripControlChars(parts[2] || '');
+    result.name = CONFIG.identityMode === 'author' ? authorName : projectName;
+    result.gitBranch = parts[2] || '';
 
     if (parts[3]) {
       for (const line of parts[3].split('\n')) {
@@ -1185,7 +1168,7 @@ function safeTerminalLink(label, url) {
   try { parsed = new URL(url); } catch { return label; }
   if (parsed.protocol !== 'https:') return label;
   if (!PROMO_LINK_HOSTS.has(parsed.hostname)) return label;
-  const cleanLabel = stripControlChars(label);
+  const cleanLabel = String(label).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
   if (cleanLabel.length === 0) return label;
   const ESC = '\u001b';
   return ESC + ']8;;' + parsed.href + ESC + '\\' + cleanLabel + ESC + ']8;;' + ESC + '\\';
@@ -1203,7 +1186,9 @@ function getPromoRow(d) {
     // as truncated instead of chopping a word mid-character (was: silent
     // slice(0,100) that could produce output that looked like corrupt data).
     const MAX_LEN = 100;
-    const sanitized = stripControlChars(promo.text);
+    const sanitized = promo.text
+      .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '')
+      ;
     const text = (sanitized.length > MAX_LEN ? sanitized.slice(0, MAX_LEN - 1).trimEnd() + '…' : sanitized).trim();
     if (text.length === 0) return null;
     // Split the label from the trailing "· manage: ruflo settings" instruction

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-06T13:58:28.616Z",
-  "gitSha": "b7bc909d",
+  "generatedAt": "2026-11-09T05:37:56.500Z",
+  "gitSha": "bc480847",
   "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/doctor.js

@@ -2214,13 +2214,15 @@ async function checkMetaharnessDeclaredPackages() {
         if (!root)
             return { name: NAME, status: 'warn', message: 'could not locate the @claude-flow/cli package root' };
         const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'));
-        const declared = Object.keys(pkg.optionalDependencies ?? {}).filter((n) => n === 'metaharness' || n.startsWith('@metaharness/'));
+        // ADR-526: @metaharness/darwin is a regular dependency; the rest stay optional.
+        const declared = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.optionalDependencies ?? {}) })
+            .filter((n) => n === 'metaharness' || n.startsWith('@metaharness/'));
         if (declared.length === 0) {
             return {
                 name: NAME,
                 status: 'fail',
-                message: 'no @metaharness/* packages declared in optionalDependencies — the dependency contract regressed (peer-only declarations are never installed)',
-                fix: 'Restore @metaharness/darwin, @metaharness/flywheel, @metaharness/radio, @metaharness/turn-credit to optionalDependencies in @claude-flow/cli',
+                message: 'no @metaharness/* packages declared in dependencies or optionalDependencies — the dependency contract regressed (peer-only declarations are never installed)',
+                fix: 'Restore @metaharness/darwin to dependencies and @metaharness/flywheel, @metaharness/radio, @metaharness/turn-credit to optionalDependencies in @claude-flow/cli',
             };
         }
         // Node resolution: nearest node_modules wins, walking upward from the CLI root.

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