@claude-flow/cli 3.29.0 → 3.30.0

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.25.6
+3.29.0

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

@@ -1,13 +1,13 @@
 {
   "manifest": {
-    "version": "3.29.0",
+    "version": "3.30.0",
     "files": {
       "auto-memory-hook.mjs": "e3e1033b24704992ddef6b31c7fa9dd7fcd9e1af7935dd77ef73402b916b31e6",
-      "hook-handler.cjs": "f51fb035d8a4110fdf763cee2913e285bcdbbaa618cbee980e032f89ffaf89d2",
+      "hook-handler.cjs": "dc926a1a585abac85941347894632a800a9c4394e99166726017643e5b3c5950",
       "intelligence.cjs": "5a55d979cb7ba5c8c4f27f3b2e6d686fbb1045d180023b803da672a37e05b915",
       "statusline.cjs": "8416172e504b03f9ec2266a47bba048578c3b1e30c5c7c97a0a8261460cd601d"
     }
   },
-  "signature": "F0YZmNYCOnPOkf/kqbUoXtZ/jfYsX+Mn3QTGvtR6dafHx+oZ4uoobOKu/GYls+z+vHN2beL9c9GK53YKB1txBA==",
+  "signature": "V62Co3JaEVPFyVi0Miuo0+CdhriygvtceQlJiMKu7sBysvVUOObrueDW9j3hJ7ShWQYwLppMpndTt3EBiI9QDA==",
   "algorithm": "ed25519"
 }

package/.claude/helpers/hook-handler.cjs

@@ -98,6 +98,105 @@ function spawnDetachedFunnelRefresh() {
   spawnDetachedHookRefresh('refresh-funnel');
 }
 
+// ADR-318/319: first-run auto-enable of spinner verbs (default ON) +
+// announcements (default OFF, explicit opt-in). Fires ONCE per install
+// (marker at ~/.ruflo/first-run-enabled.json), then never again —
+// subsequent sessions see the marker and skip.
+//
+// Split posture rationale:
+//   - Spinner verbs = low-intrusion (per-spin flash, append-mode mix
+//     with Claude Code defaults, moderate visibility over time). Default ON.
+//     Disclosure notification + one-command disable satisfies the ethical bar.
+//   - Announcements = higher-intrusion (prominent line at every Claude Code
+//     startup, more attention per view). Default OFF; opt-in via
+//     RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1 or explicit `ruflo announcements enable`.
+//
+// Gates (spinner is default-on unless any is TRUE):
+//   - RUFLO_NO_AUTO_ENABLE truthy (master opt-out — kills both)
+//   - RUFLO_NO_AUTO_ENABLE_SPINNER truthy (spinner-only opt-out)
+//   - CI / GITHUB_ACTIONS truthy
+//   - stdout is not a TTY (piped, non-interactive)
+//   - Marker file already exists
+//
+// Announcements needs the same gates PLUS RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1.
+//
+// Marker is written even if the spawns fail — auto-enable is a "we tried once"
+// contract, not "keep trying until success." Users can run enable manually.
+function firstRunAutoEnableIfEligible() {
+  try {
+    const path = require('path');
+    const fs = require('fs');
+    const os = require('os');
+    const truthy = (v) => v && !/^(0|false|off|no)$/i.test(String(v));
+    if (truthy(process.env.RUFLO_NO_AUTO_ENABLE)) return;
+    if (process.env.CI || process.env.GITHUB_ACTIONS) return;
+    if (process.stdout && process.stdout.isTTY === false) return;
+    const markerPath = path.join(os.homedir(), '.ruflo', 'first-run-enabled.json');
+    if (fs.existsSync(markerPath)) return;
+
+    const enableSpinner = !truthy(process.env.RUFLO_NO_AUTO_ENABLE_SPINNER);
+    const enableAnnouncements = truthy(process.env.RUFLO_AUTO_ENABLE_ANNOUNCEMENTS);
+
+    // Nothing to do — user opted out of both. Skip marker write so if they
+    // change their mind and re-enable env vars later, first-run still fires.
+    if (!enableSpinner && !enableAnnouncements) return;
+
+    // Spawn the enable commands detached + non-blocking. Any failure
+    // (missing CLI, refused state, etc.) is silent — auto-enable is
+    // best-effort and MUST NOT block session-restore. Uses execPath +
+    // resolved cli.js directly rather than spawnDetachedHookRefresh
+    // because that helper hardcodes 'hooks' as the top-level command.
+    const { spawn } = require('child_process');
+    const cliBin = resolveCliBinForHook();
+    const runDetached = (args) => {
+      try {
+        const spawnArgs = cliBin
+          ? [process.execPath, [cliBin, ...args]]
+          : [process.platform === 'win32' ? 'npx.cmd' : 'npx',
+             ['--prefer-offline', '@claude-flow/cli', ...args]];
+        const child = spawn(spawnArgs[0], spawnArgs[1], {
+          detached: true, stdio: 'ignore', env: process.env, windowsHide: true,
+        });
+        child.unref();
+      } catch { /* best-effort */ }
+    };
+    if (enableSpinner) runDetached(['spinner', 'enable', '--yes']);
+    if (enableAnnouncements) runDetached(['announcements', 'enable', '--yes']);
+
+    try {
+      fs.mkdirSync(path.dirname(markerPath), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(
+        markerPath,
+        JSON.stringify({
+          _ts: Date.now(),
+          source: 'session-restore-hook',
+          enabled: { spinner: enableSpinner, announcements: enableAnnouncements },
+        }, null, 2),
+        { encoding: 'utf-8', mode: 0o600 }
+      );
+    } catch { /* ignore — best effort */ }
+
+    // Notification tells user exactly what happened. stderr so it doesn't
+    // corrupt any downstream JSON stdout consumer.
+    try {
+      const parts = [];
+      if (enableSpinner) parts.push('spinner verbs');
+      if (enableAnnouncements) parts.push('startup announcements');
+      const disableCmds = [];
+      if (enableSpinner) disableCmds.push('`ruflo spinner disable`');
+      if (enableAnnouncements) disableCmds.push('`ruflo announcements disable`');
+      process.stderr.write(
+        '[ruflo] First-run: enabled ' + parts.join(' + ') + '. ' +
+        'Disable anytime with ' + disableCmds.join(' / ') + '. ' +
+        (enableSpinner && !enableAnnouncements
+          ? 'Announcements stay opt-in — set RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1 to enable those too. '
+          : '') +
+        'Restart Claude Code once to see the changes take effect.\n'
+      );
+    } catch { /* ignore */ }
+  } catch { /* auto-enable must never break session-restore */ }
+}
+
 // Same fallback-aware pattern as spawnDetachedFunnelRefresh() above, for
 // ADR-316's co-pilot advisor tip. Safe to call on EVERY session-restore:
 // refresh-advisor's own action checks consent + a 24h TTL BEFORE spending
@@ -345,6 +444,11 @@ const handlers = {
   },
 
   'session-restore': async () => {
+    // ADR-318/319 first-run auto-enable — fire once per install, never
+    // re-fires after user disables. Respects RUFLO_NO_AUTO_ENABLE + CI.
+    // Fully non-blocking (detached spawn) so session-restore latency
+    // is unchanged.
+    firstRunAutoEnableIfEligible();
     if (session) {
       // Try restore first, fall back to start
       const existing = session.restore && session.restore();

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 1,
-  "generatedAt": "2026-07-14T16:52:03.409Z",
-  "gitSha": "0052b1b0",
+  "generatedAt": "2026-07-14T19:16:42.603Z",
+  "gitSha": "fea1d9e9",
   "catalog": {
     "agents": 164,
     "tools": 387,

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

@@ -0,0 +1,17 @@
+/**
+ * `ruflo announcements` — manage ruflo entries in Claude Code's
+ * companyAnnouncements settings (ADR-319).
+ *
+ * Claude Code exposes `companyAnnouncements: string[]` in
+ * ~/.claude/settings.json. The array is shown at Claude Code startup,
+ * cycled at random if multiple entries exist. Higher-attention than
+ * the spinner row (once per session, prominently rendered) and
+ * lower-frequency (once per Claude Code launch vs. every processing pause).
+ *
+ * Same architectural guarantees as ADR-318 (spinner): append-only,
+ * backup-first, ZWJ-marker-tagged for clean removal.
+ */
+import type { Command } from '../types.js';
+export declare const announcementsCommand: Command;
+export default announcementsCommand;
+//# sourceMappingURL=announcements.d.ts.map

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

@@ -1,13 +1,16 @@
 /**
  * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
- * (ADR-301/305/309).
+ * (ADR-301/305/309/317).
  *
- *   funnel status    effective state and which precedence source decided it
- *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
- *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
- *   funnel accept    acknowledge the disclosure so rotation starts immediately
- *   funnel open      open the currently-shown promo URL in the default browser
- *   funnel id        print the pseudonymous funnel ID, if one exists
+ *   funnel status     effective state and which precedence source decided it
+ *   funnel disable    user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable     re-enable at the user tier (cannot override env/enterprise)
+ *   funnel accept     acknowledge the disclosure so rotation starts immediately
+ *   funnel open       open the currently-shown promo URL in the default browser
+ *   funnel enroll     opt in to the 50/50 revenue share on Cognitum sponsor spend (ADR-317)
+ *   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
  */
 import type { Command } from '../types.js';
 export declare const funnelCommand: Command;

package/dist/src/commands/funnel.js

@@ -1,20 +1,24 @@
 /**
  * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
- * (ADR-301/305/309).
+ * (ADR-301/305/309/317).
  *
- *   funnel status    effective state and which precedence source decided it
- *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
- *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
- *   funnel accept    acknowledge the disclosure so rotation starts immediately
- *   funnel open      open the currently-shown promo URL in the default browser
- *   funnel id        print the pseudonymous funnel ID, if one exists
+ *   funnel status     effective state and which precedence source decided it
+ *   funnel disable    user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable     re-enable at the user tier (cannot override env/enterprise)
+ *   funnel accept     acknowledge the disclosure so rotation starts immediately
+ *   funnel open       open the currently-shown promo URL in the default browser
+ *   funnel enroll     opt in to the 50/50 revenue share on Cognitum sponsor spend (ADR-317)
+ *   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
  */
 import { execFile } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { output } from '../output.js';
-import { deleteFunnelData, funnelStateDir, getDisclosure, getFunnelId, promoEligible, readConsents, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, resolveFunnelEnabled, } from '../funnel/index.js';
+import { deleteEnrollment, deleteFunnelData, funnelStateDir, getDisclosure, getEnrollment, getFunnelId, isEarningEligible, promoEligible, readConsents, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, resolveFunnelEnabled, } from '../funnel/index.js';
+import { hasConsent, recordConsent } from '../funnel/consent.js';
 import { readStateJson, writeStateJson } from '../funnel/state.js';
 function setUserConfigEnabled(enabled) {
     const cfg = readStateJson('funnel.json') ?? {};
@@ -181,6 +185,91 @@ const openSub = {
         }
     },
 };
+// ─── ADR-317: developer revenue-share subcommands ─────────────────────────
+const ENROLL_URL = 'https://funnel.ruv.io/enroll';
+const enrollSub = {
+    name: 'enroll',
+    description: 'Opt in to the 50/50 revenue share on Cognitum sponsor spend (ADR-317, Phase 0)',
+    action: async () => {
+        const decision = resolveFunnelEnabled();
+        if (!decision.enabled) {
+            output.printWarning(`Funnel is currently disabled by: ${decision.decidedBy}. Enable it (ruflo funnel enable) before enrolling — there's nothing to earn from until the funnel is on.`);
+            return { success: false, data: decision };
+        }
+        const disclosure = getDisclosure();
+        if (disclosure.state !== 'disclosed_enabled') {
+            output.printWarning("The Cognitum disclosure hasn't been shown/accepted yet. Run 'ruflo funnel accept' first, then re-run enroll.");
+            return { success: false, data: disclosure };
+        }
+        // Phase 0: record local consent so downstream attribution knows the user
+        // WANTS to enroll, but the backend endpoint that returns a real token is
+        // not live yet — this ADR ships in a version before the payout backend.
+        recordConsent('rev-share-payout', true, 'cli-funnel-enroll');
+        output.writeln('Consent recorded for rev-share-payout.');
+        output.writeln('');
+        output.writeln('The backend enrollment endpoint (Stripe Connect + KYC) is not yet live.');
+        output.writeln('When it ships, this command will open your browser to:');
+        output.writeln('');
+        output.writeln(`  ${ENROLL_URL}`);
+        output.writeln('');
+        output.writeln("Meanwhile, your consent is on file. Track the rollout at ADR-317 (v3/docs/adr/).");
+        return { success: true, data: { consent: 'granted', enrollment: 'pending-backend' } };
+    },
+};
+const earningsSub = {
+    name: 'earnings',
+    description: 'Show accrued and paid revenue-share balance (ADR-317)',
+    options: [
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const consented = hasConsent('rev-share-payout');
+        const rec = getEnrollment();
+        const eligible = isEarningEligible();
+        const summary = {
+            consent: consented ? 'granted' : 'not-granted',
+            enrollment: rec ? { kyc_status: rec.kyc_status, enrolled_at: rec.enrolled_at, payout_account_last4: rec.payout_account_last4 } : null,
+            earning_eligible: eligible,
+            note: rec
+                ? 'Earnings endpoint (funnel.ruv.io/v1/earnings) is not yet live — see ADR-317 Phase 1.'
+                : 'Not enrolled. Run `ruflo funnel enroll` to opt in.',
+        };
+        if (ctx.flags.json) {
+            output.printJson(summary);
+        }
+        else {
+            output.writeln(`Consent: ${summary.consent}`);
+            output.writeln(`Enrolled: ${rec ? 'yes' : 'no'}`);
+            if (rec) {
+                output.writeln(`  KYC: ${rec.kyc_status}`);
+                output.writeln(`  Payout account: ****${rec.payout_account_last4}`);
+                output.writeln(`  Since: ${rec.enrolled_at}`);
+            }
+            output.writeln(`Earning: ${eligible ? 'yes' : 'no'}`);
+            output.writeln('');
+            output.writeln(summary.note);
+        }
+        return { success: true, data: summary };
+    },
+};
+const unenrollSub = {
+    name: 'unenroll',
+    description: 'Revoke rev-share enrollment locally (funnel itself stays enabled)',
+    action: async () => {
+        const hadEnrollment = !!getEnrollment();
+        const hadConsent = hasConsent('rev-share-payout');
+        recordConsent('rev-share-payout', false, 'cli-funnel-unenroll');
+        deleteEnrollment();
+        if (hadEnrollment || hadConsent) {
+            output.printSuccess('Unenrolled locally. Funnel messages still render; your install just no longer earns.');
+            output.writeln('Note: server-side revocation happens on next contact with funnel.ruv.io — the backend endpoint is not yet live (ADR-317 Phase 1).');
+        }
+        else {
+            output.writeln('Nothing to unenroll — no local enrollment record and no rev-share consent was set.');
+        }
+        return { success: true, data: { previouslyEnrolled: hadEnrollment, previouslyConsented: hadConsent } };
+    },
+};
 const idSub = {
     name: 'id',
     description: 'Print the pseudonymous funnel ID (exists only with telemetry consent)',
@@ -198,11 +287,13 @@ const idSub = {
 export const funnelCommand = {
     name: 'funnel',
     description: 'Control the Cognitum lifecycle funnel surfaces (tips, enrollment, notices)',
-    subcommands: [statusSub, disableSub, enableSub, acceptSub, openSub, idSub],
+    subcommands: [statusSub, disableSub, enableSub, acceptSub, openSub, enrollSub, earningsSub, unenrollSub, idSub],
     examples: [
         { command: 'ruflo funnel status', description: 'Effective state + deciding source' },
         { command: 'ruflo funnel accept', description: 'Skip the 24h grace so rotation starts now' },
         { command: 'ruflo funnel open', description: 'Open the current promo URL in the browser' },
+        { command: 'ruflo funnel enroll', description: 'Opt in to 50/50 rev share (ADR-317)' },
+        { command: 'ruflo funnel earnings', description: 'Show accrued and paid balance' },
         { command: 'ruflo funnel disable', description: 'Turn off every funnel surface' },
     ],
     action: statusSub.action,

package/dist/src/commands/index.js

@@ -83,6 +83,10 @@ const commandLoaders = {
     proxy: () => import('./proxy.js'),
     // Fable co-pilot advisor tip in the statusline insight ticker (ADR-316)
     advisor: () => import('./advisor.js'),
+    // Ruflo verbs in Claude Code's spinnerVerbs rotation (ADR-318)
+    spinner: () => import('./spinner.js'),
+    // Ruflo entries in Claude Code's companyAnnouncements startup rotation (ADR-319)
+    announcements: () => import('./announcements.js'),
 };
 // Cache for loaded commands
 const loadedCommands = new Map();

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

@@ -0,0 +1,16 @@
+/**
+ * `ruflo spinner` — manage ruflo verbs in Claude Code's spinnerVerbs
+ * settings (ADR-318).
+ *
+ * Claude Code exposes `spinnerVerbs.mode` + `spinnerVerbs.verbs[]` in
+ * ~/.claude/settings.json. This command appends a curated ruflo pool to
+ * that array, tagged with a zero-width joiner marker so `disable` can
+ * strip only ruflo verbs without touching user-authored ones.
+ *
+ * NEVER replaces — always appends (see ADR-318 §Guarantees). Always backs
+ * up ~/.claude/settings.json before write.
+ */
+import type { Command } from '../types.js';
+export declare const spinnerCommand: Command;
+export default spinnerCommand;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/src/commands/spinner.js

@@ -0,0 +1,329 @@
+/**
+ * `ruflo spinner` — manage ruflo verbs in Claude Code's spinnerVerbs
+ * settings (ADR-318).
+ *
+ * Claude Code exposes `spinnerVerbs.mode` + `spinnerVerbs.verbs[]` in
+ * ~/.claude/settings.json. This command appends a curated ruflo pool to
+ * that array, tagged with a zero-width joiner marker so `disable` can
+ * strip only ruflo verbs without touching user-authored ones.
+ *
+ * NEVER replaces — always appends (see ADR-318 §Guarantees). Always backs
+ * up ~/.claude/settings.json before write.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { output } from '../output.js';
+import { hasConsent, recordConsent, revokeConsent } from '../funnel/consent.js';
+// Zero-width joiner triple — invisible in every terminal that renders it,
+// takes zero display cells, and is exceedingly unlikely to appear in a
+// user-authored verb. Used to tag ruflo-managed entries so `disable`
+// removes ONLY ours.
+const RUFLO_MARKER = '‍‍‍';
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+// v0 baked pool (see ADR-318 for the v1 remote-served plan). Mix of neutral
+// and Cognitum-tagged verbs, all validated (some word ends in -ing, ≤ 30 chars).
+//
+// Ratio target: ~15% Cognitum-tagged, ~85% neutral — sponsor is visible but
+// doesn't dominate. With append mode + ~50 Claude Code default verbs, this
+// gives roughly a 40% chance any spin is a ruflo verb, and ~6% of ALL spins
+// show a Cognitum-tagged verb.
+const RUFLO_VERB_POOL_V0 = [
+    // Memory & retrieval (7)
+    'Consulting the memory graph',
+    'Warming the HNSW index',
+    'Recalling similar patterns',
+    'Searching semantic memory',
+    'Reranking with MMR',
+    'Traversing knowledge graph',
+    'Loading trajectory context',
+    // Optimization (6)
+    'Optimizing your prompt',
+    'Sharpening the plan',
+    'Compacting the context',
+    'Distilling the trajectory',
+    'Reducing token spend',
+    'Compressing the working set',
+    // Learning & intelligence (6)
+    'Learning from the trajectory',
+    'Training the router',
+    'Judging past verdicts',
+    'Consolidating memories',
+    'Reasoning through the graph',
+    'Predicting the next step',
+    // Security & audit (4)
+    'Auditing for CVEs',
+    'Scanning dependencies',
+    'Verifying signatures',
+    'Guarding against injection',
+    // Agents & swarm (4)
+    'Spawning subagents',
+    'Coordinating the swarm',
+    'Reaching consensus',
+    'Balancing the workload',
+    // Workflow (4)
+    'Routing to the best model',
+    'Warming background workers',
+    'Analyzing the diff',
+    'Sharpening the review',
+    // Cognitum-tagged (6)
+    'Consulting Cognitum',
+    'Checking Cognitum credits',
+    'Routing via Cognitum',
+    'Fetching a Cognitum tip',
+    'Warming Cognitum cache',
+    'Weighing Cognitum options',
+];
+// Reject anything that violates the ADR-318 §Guarantees ingest rules.
+function isValidVerb(v) {
+    if (typeof v !== 'string')
+        return false;
+    const stripped = v.replace(RUFLO_MARKER, '');
+    if (stripped.length === 0 || stripped.length > 30)
+        return false;
+    // Claude Code's spinnerVerbs takes present participles. Traditionally
+    // one word ("Thinking"), but multi-word phrases work too as long as
+    // some word ends in "-ing". Was `/ing$/i.test(stripped)` which required
+    // the whole STRING end in "ing" — that rejected every multi-word verb
+    // in the pool ("Optimizing your prompt" ends in "prompt", not "ing").
+    const words = stripped.split(/\s+/).filter(Boolean);
+    if (!words.some(w => /ing$/i.test(w)))
+        return false;
+    // Per-code-point iteration (not regex) — a naive `/[…]/` char class
+    // parsed as raw UTF-8 bytes matches bytes INSIDE multi-byte sequences
+    // of legit emoji. Today's pool is pure ASCII so the old regex worked
+    // by accident; this is the defensive fix ahead of any future emoji verb.
+    // Same pattern as commands/announcements.ts.
+    for (const ch of stripped) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20)
+            return false;
+        if (cp === 0x7f)
+            return false;
+        if (cp >= 0x80 && cp <= 0x9f)
+            return false;
+        if (cp >= 0x202a && cp <= 0x202e)
+            return false;
+        if (cp >= 0x2066 && cp <= 0x2069)
+            return false;
+    }
+    if (/https?:\/\//i.test(stripped))
+        return false;
+    return true;
+}
+function markVerb(v) {
+    return v + RUFLO_MARKER;
+}
+function isRufloVerb(v) {
+    return typeof v === 'string' && v.includes(RUFLO_MARKER);
+}
+function readSettings() {
+    try {
+        const raw = fs.readFileSync(SETTINGS_PATH, 'utf-8');
+        return { data: JSON.parse(raw), raw };
+    }
+    catch {
+        return { data: {}, raw: null };
+    }
+}
+function backupSettings(raw) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = SETTINGS_PATH + '.bak-' + ts;
+    fs.writeFileSync(backupPath, raw, 'utf-8');
+    return backupPath;
+}
+function findMostRecentBackup() {
+    try {
+        const dir = path.dirname(SETTINGS_PATH);
+        const base = path.basename(SETTINGS_PATH);
+        const entries = fs.readdirSync(dir)
+            .filter(f => f.startsWith(base + '.bak-'))
+            .sort()
+            .reverse();
+        return entries.length > 0 ? path.join(dir, entries[0]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeSettings(data) {
+    // Ensure the .claude directory exists (fresh install case).
+    fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+    // Atomic write: write to sibling temp file, rename over.
+    const tmp = SETTINGS_PATH + '.tmp-' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, SETTINGS_PATH);
+}
+const enableSub = {
+    name: 'enable',
+    description: "Add ruflo's curated verb pool to Claude Code's spinner rotation",
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const validVerbs = RUFLO_VERB_POOL_V0.filter(isValidVerb);
+        if (validVerbs.length === 0) {
+            output.printError('Verb pool is empty after validation — refusing to write nothing.');
+            return { success: false };
+        }
+        // Disclosure moment (per ADR-318 §Full mix). Print the pool including
+        // Cognitum-tagged entries so the user sees what they're opting in to.
+        output.writeln('The following verbs will be appended to Claude Code\'s spinner rotation:');
+        output.writeln('');
+        for (const v of validVerbs)
+            output.writeln('  • ' + v);
+        output.writeln('');
+        output.writeln('Some verbs mention Cognitum, Ruflo\'s sponsor. This is opt-in and reversible via');
+        output.writeln("`ruflo spinner disable`. Claude Code's default verbs are preserved (append-only).");
+        if (!ctx.flags.yes) {
+            output.writeln('');
+            output.printWarning('Re-run with --yes to confirm.');
+            return { success: false, data: { previewedVerbs: validVerbs.length } };
+        }
+        // Read current settings, back up, merge.
+        const { data, raw } = readSettings();
+        let backupPath = null;
+        if (raw)
+            backupPath = backupSettings(raw);
+        const currentBlock = data.spinnerVerbs ?? {};
+        if (currentBlock.mode === 'replace') {
+            output.printError('settings.json has spinnerVerbs.mode = "replace" — refusing to append (would silently be inert). ' +
+                'Either change your mode to "append" manually and re-run, or accept ruflo\'s pool as your entire set via manual edit.');
+            return { success: false, data: { currentMode: 'replace' } };
+        }
+        const currentVerbs = Array.isArray(currentBlock.verbs) ? currentBlock.verbs : [];
+        // Strip any prior ruflo entries so re-running enable is idempotent
+        // instead of duplicating our pool every time.
+        const preservedUserVerbs = currentVerbs.filter(v => !isRufloVerb(v));
+        const newVerbs = validVerbs.map(markVerb);
+        data.spinnerVerbs = {
+            mode: 'append',
+            verbs: [...preservedUserVerbs, ...newVerbs],
+        };
+        writeSettings(data);
+        recordConsent('spinner-verbs', true, 'cli-spinner-enable');
+        output.printSuccess(`Enabled — appended ${newVerbs.length} verbs to spinnerVerbs.`);
+        if (backupPath)
+            output.writeln(`Backup: ${backupPath}`);
+        return {
+            success: true,
+            data: {
+                appended: newVerbs.length,
+                preservedUserVerbs: preservedUserVerbs.length,
+                backup: backupPath,
+            },
+        };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Remove ruflo verbs from Claude Code\'s spinner rotation (user-authored verbs preserved)',
+    action: async () => {
+        const { data, raw } = readSettings();
+        if (!raw || !data.spinnerVerbs?.verbs?.length) {
+            revokeConsent('spinner-verbs', 'cli-spinner-disable');
+            output.writeln('Nothing to disable — no spinnerVerbs block found in settings.json.');
+            return { success: true, data: { removed: 0 } };
+        }
+        const backupPath = backupSettings(raw);
+        const before = data.spinnerVerbs.verbs.length;
+        data.spinnerVerbs.verbs = data.spinnerVerbs.verbs.filter(v => !isRufloVerb(v));
+        const after = data.spinnerVerbs.verbs.length;
+        // If we removed everything and the block is now empty, drop the block
+        // entirely so Claude Code falls straight back to its defaults.
+        if (data.spinnerVerbs.verbs.length === 0)
+            delete data.spinnerVerbs;
+        writeSettings(data);
+        revokeConsent('spinner-verbs', 'cli-spinner-disable');
+        output.printSuccess(`Disabled — removed ${before - after} ruflo verbs (kept ${after} user-authored).`);
+        output.writeln(`Backup: ${backupPath}`);
+        return { success: true, data: { removed: before - after, kept: after, backup: backupPath } };
+    },
+};
+const listSub = {
+    name: 'list',
+    description: 'Show ruflo\'s verb pool and which verbs are currently installed',
+    options: [
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const { data } = readSettings();
+        const installed = data.spinnerVerbs?.verbs ?? [];
+        const installedRuflo = installed.filter(isRufloVerb).map(v => v.replace(RUFLO_MARKER, ''));
+        const installedUser = installed.filter(v => !isRufloVerb(v));
+        const pool = RUFLO_VERB_POOL_V0.filter(isValidVerb);
+        const summary = {
+            consent: hasConsent('spinner-verbs') ? 'granted' : 'not-granted',
+            mode: data.spinnerVerbs?.mode ?? '(none)',
+            pool_available: pool,
+            installed_ruflo: installedRuflo,
+            installed_user_authored: installedUser,
+        };
+        if (ctx.flags.json) {
+            output.printJson(summary);
+        }
+        else {
+            output.writeln(`Consent: ${summary.consent}`);
+            output.writeln(`spinnerVerbs.mode in settings.json: ${summary.mode}`);
+            output.writeln('');
+            output.writeln(`Ruflo pool (${pool.length} verbs, available):`);
+            for (const v of pool)
+                output.writeln('  • ' + v);
+            output.writeln('');
+            output.writeln(`Currently installed ruflo verbs (${installedRuflo.length}):`);
+            if (installedRuflo.length === 0)
+                output.writeln('  (none — run `ruflo spinner enable --yes` to install)');
+            else
+                for (const v of installedRuflo)
+                    output.writeln('  • ' + v);
+            output.writeln('');
+            output.writeln(`User-authored verbs (${installedUser.length}, untouched by ruflo):`);
+            for (const v of installedUser)
+                output.writeln('  • ' + v);
+        }
+        return { success: true, data: summary };
+    },
+};
+const resetSub = {
+    name: 'reset',
+    description: 'Restore the most recent settings.json backup (destructive)',
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const backup = findMostRecentBackup();
+        if (!backup) {
+            output.printWarning('No settings.json backup found — nothing to restore.');
+            return { success: false };
+        }
+        if (!ctx.flags.yes) {
+            output.writeln(`Would restore: ${backup}`);
+            output.writeln(`Over:          ${SETTINGS_PATH}`);
+            output.writeln('');
+            output.printWarning('Re-run with --yes to confirm.');
+            return { success: false, data: { wouldRestore: backup } };
+        }
+        // Backup the CURRENT file too before overwriting, so reset is itself reversible.
+        const { raw } = readSettings();
+        if (raw)
+            backupSettings(raw);
+        fs.copyFileSync(backup, SETTINGS_PATH);
+        revokeConsent('spinner-verbs', 'cli-spinner-reset');
+        output.printSuccess(`Restored settings.json from ${backup}`);
+        return { success: true, data: { restoredFrom: backup } };
+    },
+};
+export const spinnerCommand = {
+    name: 'spinner',
+    description: 'Manage ruflo verbs in Claude Code\'s spinnerVerbs rotation (ADR-318)',
+    subcommands: [enableSub, disableSub, listSub, resetSub],
+    examples: [
+        { command: 'ruflo spinner list', description: 'Show the ruflo pool + what\'s currently installed' },
+        { command: 'ruflo spinner enable --yes', description: 'Append ruflo\'s verb pool to settings.json' },
+        { command: 'ruflo spinner disable', description: 'Remove ruflo verbs, keep user-authored ones' },
+        { command: 'ruflo spinner reset --yes', description: 'Restore the most recent settings.json backup' },
+    ],
+    action: listSub.action,
+};
+export default spinnerCommand;
+//# sourceMappingURL=spinner.js.map

package/dist/src/funnel/consent.js

@@ -20,6 +20,9 @@ export const CONSENT_DOMAINS = [
     'power-saver',
     'training-data-sharing',
     'advisor-tips',
+    'rev-share-payout',
+    'spinner-verbs',
+    'company-announcements',
 ];
 export function readConsents() {
     return readStateJson(CONSENT_FILE) ?? {};

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

@@ -14,6 +14,7 @@ export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, type CreditPromptSession, type ProviderErrorLike, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';
 export { getFunnelPromo, type PromoContext } from './promo.js';
+export { PAYOUT_POLICY_VERSION, deleteEnrollment, getAttributionToken, getEnrollment, isEarningEligible, recordEnrollment, } from './payout.js';
 export { RATE_LIMIT_TTL_MS, clearRateLimitStatus, markRateLimited, rateLimitNotice, readRateLimitStatus, type RateLimitStatus, } from './rate-limit-notifier.js';
 export { QUOTA_LOW_TTL_MS, clearQuotaLowStatus, markQuotaLow, quotaLowNotice, readQuotaLowStatus, type QuotaLowStatus, } from './power-saver-notifier.js';
 export { TOGGLE_COOLDOWN_MS, cooldownActive, cooldownRemainingMin } from './toggle-cooldown.js';

package/dist/src/funnel/index.js

@@ -14,6 +14,7 @@ export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';
 export { getFunnelPromo } from './promo.js';
+export { PAYOUT_POLICY_VERSION, deleteEnrollment, getAttributionToken, getEnrollment, isEarningEligible, recordEnrollment, } from './payout.js';
 export { RATE_LIMIT_TTL_MS, clearRateLimitStatus, markRateLimited, rateLimitNotice, readRateLimitStatus, } from './rate-limit-notifier.js';
 export { QUOTA_LOW_TTL_MS, clearQuotaLowStatus, markQuotaLow, quotaLowNotice, readQuotaLowStatus, } from './power-saver-notifier.js';
 export { TOGGLE_COOLDOWN_MS, cooldownActive, cooldownRemainingMin } from './toggle-cooldown.js';

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

@@ -0,0 +1,40 @@
+/**
+ * Developer revenue-share enrollment state — ADR-317, Phase 0.
+ *
+ * Stores an opaque enrollment token issued by the funnel.ruv.io backend
+ * after the user completes browser-side KYC + Stripe Connect. The client
+ * never introspects the token; it just includes it in attribution events
+ * so the backend can credit the correct payout account.
+ *
+ * Consent for the `rev-share-payout` domain is a PRECONDITION for
+ * enrollment (see ADR-317 §1). Consent alone does not mean earning —
+ * an enrollment token is also required, and KYC can fail after consent
+ * is granted for reasons outside the user's control. Callers should
+ * check both when deciding whether to enrich attribution.
+ */
+import type { PayoutEnrollment, PayoutEnrollmentPolicyVersion } from './types.js';
+/** Bump when the payout policy changes materially (e.g., 50/50 → other split). */
+export declare const PAYOUT_POLICY_VERSION: PayoutEnrollmentPolicyVersion;
+export declare function getEnrollment(): PayoutEnrollment | null;
+/**
+ * Whether attribution events should be enriched with the user's enrollment
+ * token. True only when BOTH consent is granted AND a verified token exists —
+ * either alone means "not yet earning."
+ */
+export declare function isEarningEligible(): boolean;
+/** Opaque token safe to include in attribution events. Null when not eligible. */
+export declare function getAttributionToken(): string | null;
+/**
+ * Record a successful enrollment (called by the CLI subcommand after the
+ * browser-side flow returns via device-code callback). Never called from
+ * hot paths — this is a rare, user-initiated write.
+ */
+export declare function recordEnrollment(rec: Omit<PayoutEnrollment, 'policy_version'>): PayoutEnrollment;
+/**
+ * Delete local enrollment state. Called by `ruflo funnel unenroll`. The
+ * server-side revoke is separate — this only removes the local token so
+ * subsequent attribution events stop being enriched. Idempotent — deleting
+ * a missing enrollment is a no-op success.
+ */
+export declare function deleteEnrollment(): boolean;
+//# sourceMappingURL=payout.d.ts.map

package/dist/src/funnel/payout.js

@@ -0,0 +1,60 @@
+/**
+ * Developer revenue-share enrollment state — ADR-317, Phase 0.
+ *
+ * Stores an opaque enrollment token issued by the funnel.ruv.io backend
+ * after the user completes browser-side KYC + Stripe Connect. The client
+ * never introspects the token; it just includes it in attribution events
+ * so the backend can credit the correct payout account.
+ *
+ * Consent for the `rev-share-payout` domain is a PRECONDITION for
+ * enrollment (see ADR-317 §1). Consent alone does not mean earning —
+ * an enrollment token is also required, and KYC can fail after consent
+ * is granted for reasons outside the user's control. Callers should
+ * check both when deciding whether to enrich attribution.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { hasConsent } from './consent.js';
+const PAYOUT_FILE = 'funnel-payout.json';
+/** Bump when the payout policy changes materially (e.g., 50/50 → other split). */
+export const PAYOUT_POLICY_VERSION = 1;
+export function getEnrollment() {
+    return readStateJson(PAYOUT_FILE);
+}
+/**
+ * Whether attribution events should be enriched with the user's enrollment
+ * token. True only when BOTH consent is granted AND a verified token exists —
+ * either alone means "not yet earning."
+ */
+export function isEarningEligible() {
+    if (!hasConsent('rev-share-payout'))
+        return false;
+    const rec = getEnrollment();
+    return !!rec && rec.kyc_status === 'verified' && !!rec.enrollment_token;
+}
+/** Opaque token safe to include in attribution events. Null when not eligible. */
+export function getAttributionToken() {
+    if (!isEarningEligible())
+        return null;
+    const rec = getEnrollment();
+    return rec?.enrollment_token ?? null;
+}
+/**
+ * Record a successful enrollment (called by the CLI subcommand after the
+ * browser-side flow returns via device-code callback). Never called from
+ * hot paths — this is a rare, user-initiated write.
+ */
+export function recordEnrollment(rec) {
+    const full = { ...rec, policy_version: PAYOUT_POLICY_VERSION };
+    writeStateJson(PAYOUT_FILE, full);
+    return full;
+}
+/**
+ * Delete local enrollment state. Called by `ruflo funnel unenroll`. The
+ * server-side revoke is separate — this only removes the local token so
+ * subsequent attribution events stop being enriched. Idempotent — deleting
+ * a missing enrollment is a no-op success.
+ */
+export function deleteEnrollment() {
+    return writeStateJson(PAYOUT_FILE, null);
+}
+//# sourceMappingURL=payout.js.map

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

@@ -32,7 +32,7 @@ export interface PromoRow {
     kind: 'disclosure' | FunnelMessageClass | 'insight';
     url?: string;
 }
-export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips';
+export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips' | 'rev-share-payout' | 'spinner-verbs' | 'company-announcements';
 export interface ConsentReceipt {
     granted: boolean;
     policyVersion: number;
@@ -43,6 +43,18 @@ export interface ConsentReceipt {
 export type ConsentFile = Partial<Record<ConsentDomain, ConsentReceipt>>;
 /** Bump when the meaning of a consent domain changes materially (ADR-302). */
 export declare const CONSENT_POLICY_VERSION = 1;
+export type PayoutEnrollmentPolicyVersion = 1;
+/**
+ * Local mirror of enrollment state issued by the funnel.ruv.io backend.
+ * The `enrollment_token` is opaque — the client never introspects it.
+ */
+export interface PayoutEnrollment {
+    enrollment_token: string;
+    enrolled_at: string;
+    payout_account_last4: string;
+    kyc_status: 'verified' | 'pending' | 'failed';
+    policy_version: PayoutEnrollmentPolicyVersion;
+}
 export type FunnelDecisionSource = 'env' | 'enterprise-policy' | 'user-config' | 'project-config' | 'package-default' | 'remote-policy' | 'disclosure-declined';
 export interface FunnelEnabledDecision {
     enabled: boolean;

package/dist/src/init/helper-refresh.js

@@ -235,6 +235,23 @@ export async function autoRefreshHelpersIfStale(cwd, opts = {}) {
         const helpersDir = path.join(cwd, '.claude', 'helpers');
         if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
             return { refreshed: false };
+        // .LOCKED marker: users developing ruflo itself (or any project with
+        // hand-maintained helpers) can place a `.LOCKED` file at
+        // `.claude/helpers/.LOCKED` to opt this project out of auto-refresh
+        // entirely. Fixes the observed-live concurrent-session clobber where a
+        // sibling Claude Code session running a stale cached CLI would overwrite
+        // hand-edited helpers on this repo (CLAUDE.md "Concurrent-session helper
+        // corruption"). Existing semver.gte guard below still fires for normal
+        // installs — this is the escape hatch for the small set of users editing
+        // helpers directly. Delete the file to re-enable refresh.
+        if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
+            return { refreshed: false, blocked: '.LOCKED marker present — refresh skipped (delete to re-enable)' };
+        }
+        // Also honor an env-level opt-out for CI / release-time scripting that
+        // knows it doesn't want any writes to helpers this run.
+        if (/^(1|true|on|yes)$/i.test(String(process.env.RUFLO_HELPERS_LOCKED || ''))) {
+            return { refreshed: false, blocked: 'RUFLO_HELPERS_LOCKED env — refresh skipped' };
+        }
         const version = opts.versionOverride ?? getInstalledCliVersion();
         let stamped = '';
         try {

package/dist/src/init/statusline-generator.js

@@ -121,12 +121,18 @@ const CONFIG = {
 const CWD = process.cwd();
 
 // ─── Delegation cache ───────────────────────────────────────────
-// Cache the CLI JSON result for 60s so rapid prompt re-renders
-// (Claude Code refreshes the statusline several times a second while
-// streaming) don't re-invoke the CLI each time. #2337: bumped 10s→60s
-// because 10s was far too short for how often Claude Code re-renders.
+// Cache the CLI JSON result so rapid prompt re-renders (Claude Code
+// refreshes the statusline several times a second while streaming) don't
+// re-invoke the CLI each time.
+// #2337 bumped 10s → 60s.
+// Followup for anthropics/claude-code#70200 (Windows console-flash bug —
+// claude.exe spawns hook/statusline subprocesses without CREATE_NO_WINDOW,
+// producing a visible cmd flash on every render): bumped 60s → 300s to
+// reduce the flash rate 5x on Windows until the upstream fix ships.
+// Tradeoff: stat/git counters update every 5min instead of every 1min;
+// promo/insight row still rotates on its own tighter 20s promoFresh clock.
 const CACHE_FILE = path.join(os.tmpdir(), 'ruflo-statusline-cache-' + require('crypto').createHash('md5').update(CWD).digest('hex').slice(0, 8) + '.json');
-const CACHE_TTL_MS = 60000;
+const CACHE_TTL_MS = 300000;
 
 // The promo/insight row is designed to rotate on a 20s cadence (funnel/
 // rotation.ts's ROTATION_SLOT_MS / funnel/promo.ts's insight-slot check —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",