claude-flow 3.27.4 → 3.28.0

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

@@ -15,9 +15,99 @@
 
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
 
 const helpersDir = __dirname;
 
+// Resolve an installed @claude-flow/cli (or ruflo) bin — mirrors
+// statusline-generator.ts's resolveCliBin() candidate list. Used only to
+// spawn the detached funnel-refresh helper below; failures are silent (no
+// candidate found just means the refresh never fires this session).
+//
+// Verifies dist/src/index.js exists alongside bin/cli.js, not just the bin
+// itself — Claude Code's own plugin marketplace mechanism installs by
+// `git clone`/`git pull` with no build step, so `~/.claude/plugins/
+// marketplaces/ruflo` is a SOURCE-ONLY checkout by construction: bin/cli.js
+// is present on disk but importing dist/src/index.js throws
+// ERR_MODULE_NOT_FOUND on every real command (confirmed live — only
+// `--version` happens to survive it, since it reads package.json directly).
+// Without this check, resolveCliBinForHook() picked that doomed candidate
+// first every time and spawnDetachedFunnelRefresh() below had no fallback,
+// so the promo/disclosure row could never populate for any marketplace
+// install, on any OS.
+function resolveCliBinForHook() {
+  try {
+    const home = os.homedir();
+    const cwd = process.cwd();
+    const candidates = [
+      path.join(home, '.claude', 'plugins', 'marketplaces', 'ruflo', 'bin', 'cli.js'),
+      path.join(cwd, 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),
+      path.join(cwd, 'node_modules', 'ruflo', 'bin', 'cli.js'),
+      path.join(cwd, 'v3', '@claude-flow', 'cli', 'bin', 'cli.js'),
+      // helpersDir is .claude/helpers/ inside the package itself when this
+      // file is running from a real @claude-flow/cli install (not a project
+      // that merely copied the helper) — its bin/ is two levels up.
+      path.join(helpersDir, '..', '..', 'bin', 'cli.js'),
+    ];
+    for (const p of candidates) {
+      try {
+        if (fs.existsSync(p) && fs.existsSync(path.join(path.dirname(p), '..', 'dist', 'src', 'index.js'))) {
+          return p;
+        }
+      } catch (e) { /* try next candidate */ }
+    }
+  } catch (e) { /* ignore */ }
+  return null;
+}
+
+// Fire-and-forget doesn't work when the CALLER is itself a short-lived
+// subprocess (confirmed live: two consecutive statusline renders 5s apart
+// both saw an empty funnel-messages-cache, because the async HTTPS fetch
+// inside a `void refreshRemoteMessages()` call gets killed when the spawning
+// process exits before the request completes). Spawning fully DETACHED +
+// unref'd decouples the refresh's lifetime from this hook's — it keeps
+// running (up to message-transport.ts's own 4s fetch timeout) even after
+// session-restore's own process has already exited, so it actually gets a
+// chance to write the cache. Never awaited here — must not add to
+// SessionStart's own timeout budget.
+//
+// No usable local candidate (resolveCliBinForHook() returned null) falls
+// back to npx: this call is detached/unref'd, so a slower npx cold-start
+// costs nothing perceptible — unlike the statusline's own synchronous
+// render path, where local-first exists purely for per-render latency.
+// `--prefer-offline` avoids a registry round trip for the tarball when
+// already cached while still resolving the current `@latest` version.
+function spawnDetachedHookRefresh(subcommand) {
+  try {
+    const { spawn } = require('child_process');
+    const cliBin = resolveCliBinForHook();
+    const cmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    const spawnArgs = cliBin
+      ? [process.execPath, [cliBin, 'hooks', subcommand, '--quiet']]
+      : [cmd, ['--prefer-offline', '@claude-flow/cli', 'hooks', subcommand, '--quiet']];
+    const child = spawn(spawnArgs[0], spawnArgs[1], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
+    child.unref();
+  } catch (e) { /* best-effort only */ }
+}
+
+function spawnDetachedFunnelRefresh() {
+  spawnDetachedHookRefresh('refresh-funnel');
+}
+
+// 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
+// anything, so an unconsented or already-fresh install is a fast no-op file
+// read, never a network call. Never awaited here — must not add to
+// SessionStart's own timeout budget.
+function spawnDetachedAdvisorRefresh() {
+  spawnDetachedHookRefresh('refresh-advisor');
+}
+
 // Safe require with stdout suppression - the helper modules have CLI
 // sections that run unconditionally on require(), so we mute console
 // during the require to prevent noisy output.
@@ -168,6 +258,57 @@ const handlers = {
     } else {
       console.log('[INFO] Router not available, using default routing');
     }
+
+    // Rate-limit -> sponsored-capacity nudge (ADR-312/313). Fires here,
+    // client-side, BEFORE the API call this prompt would make — so it still
+    // reaches the transcript even if that call then fails from the rate
+    // limit. Cheap local file reads only; never a network call or a child
+    // process, so it cannot add latency to prompt submission.
+    try {
+      const rlFunnelEnv = process.env.RUFLO_FUNNEL;
+      const rlDisabledByEnv = rlFunnelEnv !== undefined && /^(0|false|off|no)$/i.test(String(rlFunnelEnv).trim());
+      const rlCiVars = ['CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'TRAVIS', 'BUILDKITE', 'JENKINS_URL', 'TEAMCITY_VERSION', 'TF_BUILD'];
+      const rlIsCi = rlCiVars.some((v) => {
+        const val = process.env[v];
+        return val !== undefined && val !== '' && val !== '0' && String(val).toLowerCase() !== 'false';
+      });
+      const rlHome = path.join(os.homedir(), '.ruflo');
+      let rlUserDisabled = false;
+      try {
+        const rlUserCfg = JSON.parse(fs.readFileSync(path.join(rlHome, 'funnel.json'), 'utf8'));
+        rlUserDisabled = !!(rlUserCfg && rlUserCfg.enabled === false);
+      } catch (e) { /* absent/malformed = not disabled */ }
+      let rlProjectDisabled = false;
+      try {
+        const rlProjCfg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'claude-flow.config.json'), 'utf8'));
+        rlProjectDisabled = !!(rlProjCfg && rlProjCfg.funnel && rlProjCfg.funnel.enabled === false);
+      } catch (e) { /* absent/malformed = not disabled */ }
+
+      if (!rlDisabledByEnv && !rlIsCi && !rlUserDisabled && !rlProjectDisabled) {
+        let rlStatus = null;
+        try { rlStatus = JSON.parse(fs.readFileSync(path.join(rlHome, 'rate-limit-status.json'), 'utf8')); } catch (e) { /* not flagged */ }
+        let rlIsLimited = false;
+        if (rlStatus && rlStatus.limited) {
+          if (rlStatus.since) {
+            const rlSinceMs = Date.parse(rlStatus.since);
+            rlIsLimited = isNaN(rlSinceMs) ? true : (Date.now() - rlSinceMs) < 6 * 60 * 60 * 1000;
+          } else {
+            rlIsLimited = true;
+          }
+        }
+        if (rlIsLimited) {
+          let rlConsented = false;
+          try {
+            const rlConsentFile = JSON.parse(fs.readFileSync(path.join(rlHome, 'consent.json'), 'utf8'));
+            const rlReceipt = rlConsentFile && rlConsentFile['sponsored-downtime'];
+            rlConsented = !!(rlReceipt && rlReceipt.granted === true && rlReceipt.at !== null && rlReceipt.policyVersion === 1);
+          } catch (e) { /* not consented */ }
+          if (!rlConsented) {
+            console.log('[COGNITUM] Hit your Claude usage limit? Free sponsored capacity is available at cognitum.one/meta-llm — run: ruflo proxy sponsor-enable --yes');
+          }
+        }
+      }
+    } catch (e) { /* nudge must never break the hook */ }
   },
 
   'pre-bash': () => {
@@ -234,6 +375,14 @@ const handlers = {
         console.log(`[INTELLIGENCE] Loaded ${initResult.nodes} patterns, ${initResult.edges} edges`);
       }
     }
+    // Warm the funnel message cache once per session (see
+    // spawnDetachedFunnelRefresh's doc comment for why this must happen
+    // here, detached, rather than as the statusline's own fire-and-forget).
+    spawnDetachedFunnelRefresh();
+    // ADR-316 co-pilot advisor tip — same detached pattern; cheap no-op
+    // when not consented or still within the 24h TTL (see refresh-advisor's
+    // own doc comment).
+    spawnDetachedAdvisorRefresh();
   },
 
   'session-end': async () => {

package/.claude/helpers/intelligence.cjs

@@ -587,6 +587,16 @@ function recordEdit(file, success) {
     sessionId: sessionGet('sessionId') || null,
   });
   fs.appendFileSync(PENDING_PATH, entry + '\n', 'utf-8');
+  // Runaway-storage guard: pending-insights is append-only and only drained by
+  // consolidation. If it grows past ~512KB (thousands of un-consolidated edits
+  // — e.g. the daemon never ran), keep only the most recent 2000 lines so it
+  // can never grow unbounded. Cheap (a statSync per edit; rewrite only when over).
+  try {
+    if (fs.statSync(PENDING_PATH).size > 512 * 1024) {
+      const lines = fs.readFileSync(PENDING_PATH, 'utf-8').split('\n').filter(Boolean);
+      if (lines.length > 2000) fs.writeFileSync(PENDING_PATH, lines.slice(-2000).join('\n') + '\n', 'utf-8');
+    }
+  } catch (e) { /* non-fatal */ }
 }
 
 /**

package/.claude/helpers/statusline.cjs

@@ -618,7 +618,7 @@ function getPkgVersion() {
   // version (see generateStatuslineScript()'s doc comment) — correct even
   // when this renders via a pure npx invocation with no local install for
   // the candidate scan below to find.
-  let ver = "3.27.4";
+  let ver = "3.28.0";
   try {
     const home = os.homedir();
     const pkgPaths = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.27.4",
+  "version": "3.28.0",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 1,
-  "generatedAt": "2026-07-14T04:41:45.824Z",
-  "gitSha": "b254e321",
+  "generatedAt": "2026-07-14T05:33:57.949Z",
+  "gitSha": "f2208820",
   "catalog": {
     "agents": 164,
     "tools": 387,

package/v3/@claude-flow/cli/dist/src/commands/daemon.d.ts

@@ -31,6 +31,29 @@ export declare function daemonCommandLineBelongsToWorkspace(commandLine: string,
  * Returns null for pre-#1914 daemons that never stamped a workspace.
  */
 export declare function extractWorkspaceFromDaemonLine(commandLine: string): string | null;
+/**
+ * #2661 root-fix — one-time upgrade migration warning. A user who had
+ * `aiWorkersEnabled: true` configured BEFORE this fix landed (old config
+ * file or RUFLO_DAEMON_AI_WORKERS=1) and already has multiple worktree
+ * daemons running is exactly the P0 scenario the issue describes — surface
+ * it plainly, ONCE ever (not on every `daemon start`, which would just be
+ * noise once the user has seen and acted on it). The supervisor/lease
+ * mechanism (task #9) already makes only one of those daemons actually
+ * schedule AI workers going forward; this warning's job is purely to make
+ * a pre-existing fleet VISIBLE the first time this code runs, not to take
+ * any destructive action — nothing here stops or kills another daemon.
+ *
+ * `opts` exists for tests ONLY, mirroring the injectable-dependency pattern
+ * used elsewhere in this codebase (e.g. helper-refresh.ts's
+ * sourceDirOverride) — real callers always use the defaults.
+ */
+export declare function maybeShowMultiDaemonMigrationWarning(opts?: {
+    markerFile?: string;
+    fleetScanner?: () => Promise<Array<{
+        pid: number;
+        workspace: string | null;
+    }>>;
+}): Promise<void>;
 export declare const daemonCommand: Command;
 export default daemonCommand;
 //# sourceMappingURL=daemon.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/daemon.js

@@ -7,6 +7,7 @@ import { getDaemon, startDaemon, stopDaemon } from '../services/worker-daemon.js
 import { fork } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
 import * as fs from 'fs';
 // Start daemon subcommand
 const startCommand = {
@@ -580,6 +581,11 @@ async function startBackgroundDaemon(projectRoot, quiet, forwarded = {}) {
             }
         }
         catch { /* best-effort visibility — never fail the start */ }
+        // #2661 root-fix — one-time migration warning for a pre-existing
+        // multi-daemon fleet that already had AI workers enabled before this
+        // fix landed. Separate from the always-shown notice above: this one
+        // fires at most once ever, and only for the genuinely risky shape.
+        await maybeShowMultiDaemonMigrationWarning();
     }
     return { success: true };
 }
@@ -942,6 +948,68 @@ async function scanRunningDaemons() {
         return [];
     }
 }
+function defaultMultiDaemonWarningMarker() {
+    return join(homedir(), '.claude-flow', 'multi-daemon-warning-shown.json');
+}
+/**
+ * #2661 root-fix — one-time upgrade migration warning. A user who had
+ * `aiWorkersEnabled: true` configured BEFORE this fix landed (old config
+ * file or RUFLO_DAEMON_AI_WORKERS=1) and already has multiple worktree
+ * daemons running is exactly the P0 scenario the issue describes — surface
+ * it plainly, ONCE ever (not on every `daemon start`, which would just be
+ * noise once the user has seen and acted on it). The supervisor/lease
+ * mechanism (task #9) already makes only one of those daemons actually
+ * schedule AI workers going forward; this warning's job is purely to make
+ * a pre-existing fleet VISIBLE the first time this code runs, not to take
+ * any destructive action — nothing here stops or kills another daemon.
+ *
+ * `opts` exists for tests ONLY, mirroring the injectable-dependency pattern
+ * used elsewhere in this codebase (e.g. helper-refresh.ts's
+ * sourceDirOverride) — real callers always use the defaults.
+ */
+export async function maybeShowMultiDaemonMigrationWarning(opts) {
+    const markerFile = opts?.markerFile ?? defaultMultiDaemonWarningMarker();
+    try {
+        if (fs.existsSync(markerFile))
+            return;
+        const fleet = await (opts?.fleetScanner ?? scanRunningDaemons)();
+        if (fleet.length <= 1)
+            return;
+        let anyAiEnabled = false;
+        for (const d of fleet) {
+            if (!d.workspace)
+                continue;
+            try {
+                const statePath = join(d.workspace, '.claude-flow', 'daemon-state.json');
+                if (!fs.existsSync(statePath))
+                    continue;
+                const st = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+                if (st?.config?.aiWorkersEnabled === true) {
+                    anyAiEnabled = true;
+                    break;
+                }
+            }
+            catch { /* unreadable state — skip this daemon */ }
+        }
+        // Only the genuinely risky shape (pre-existing fleet + AI workers
+        // enabled somewhere in it) warrants the migration warning. A harmless
+        // multi-daemon fleet with AI workers off everywhere already gets the
+        // lighter, always-shown fleet-size notice at daemon start.
+        if (anyAiEnabled) {
+            output.writeln();
+            output.printWarning(`Ruflo found ${fleet.length} worktree daemons. Scheduled AI workers are now supervisor-gated.`);
+            output.printInfo('Inspect:                      ruflo daemon status --all');
+            output.printInfo('Stop all:                      ruflo daemon stop --all');
+            output.printInfo('Pause autonomous launches:     ruflo daemon budget pause');
+            output.writeln();
+        }
+        const dir = dirname(markerFile);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(markerFile, JSON.stringify({ shownAt: new Date().toISOString(), fleetSize: fleet.length, anyAiEnabled }), { mode: 0o600 });
+    }
+    catch { /* best-effort visibility — never fail the command */ }
+}
 /**
  * #2356: render the global `daemon status --all` view. For each running daemon
  * it reads that workspace's daemon-state.json to show age + configured TTL,
@@ -1010,6 +1078,39 @@ async function renderAllDaemonsStatus() {
     if (daemons.length > 1) {
         output.printInfo('Stop all daemons across workspaces with: ruflo daemon stop --all');
     }
+    // #2661 root-fix — repository supervisor state, one row per distinct
+    // repository among the scanned daemons' workspaces. Resolving identity
+    // per workspace is cheap (a couple of `git rev-parse` calls, cached).
+    try {
+        const { resolveGitWorkspaceIdentity } = await import('../services/git-workspace-identity.js');
+        const { getRepoSupervisorRegistry } = await import('../services/repo-supervisor.js');
+        const { getWorkspaceLeaseRegistry } = await import('../services/workspace-lease.js');
+        const seenRepos = new Map(); // repositoryId -> a representative workspace path
+        for (const d of daemons) {
+            if (!d.workspace)
+                continue;
+            const identity = resolveGitWorkspaceIdentity(d.workspace);
+            if (identity.isGit && !seenRepos.has(identity.repositoryId)) {
+                seenRepos.set(identity.repositoryId, d.workspace);
+            }
+        }
+        if (seenRepos.size > 0) {
+            const supervisorReg = getRepoSupervisorRegistry();
+            const leaseReg = getWorkspaceLeaseRegistry();
+            const lines = [];
+            for (const [repositoryId, sampleWorkspace] of seenRepos) {
+                const record = supervisorReg.getRecord(repositoryId);
+                const activeLeases = leaseReg.listActive(repositoryId).length;
+                const label = repositoryId.slice(0, 12);
+                lines.push(record
+                    ? `  ${label}…  supervisor: ${record.worktreeRoot} (pid ${record.pid})  |  active leases: ${activeLeases}`
+                    : `  ${label}…  supervisor: ${output.dim('none elected')}  |  active leases: ${activeLeases}`);
+            }
+            output.writeln();
+            output.printBox(lines.join('\n'), 'Repository Supervisors (#2661 root-fix)');
+        }
+    }
+    catch { /* supervisor registry unavailable — skip the panel */ }
     // #2661: user-global AI launch usage — the shared budget every daemon
     // draws from, independent of worktree count.
     try {
@@ -1496,6 +1597,76 @@ const uninstallSupervisorCommand = {
         return { success: false, exitCode: 1 };
     },
 };
+// #2661 root-fix — `daemon budget show|pause|resume`. The budget state was
+// previously visible only inline in `daemon status --all`; these give it an
+// independently scriptable surface (e.g. `ruflo daemon budget pause` before
+// a long interactive session, `... resume` after).
+const budgetShowCommand = {
+    name: 'show',
+    description: 'Show the user-global AI launch budget (launches, active children, circuit-breaker state)',
+    options: [],
+    examples: [{ command: 'claude-flow daemon budget show', description: 'Show current budget usage and limits' }],
+    action: async () => {
+        const { getGlobalAiBudget } = await import('../services/global-ai-budget.js');
+        const budget = getGlobalAiBudget();
+        const usage = budget.getUsage();
+        const limits = budget.getLimits();
+        output.writeln();
+        const byWs = usage.byWorkspace.slice(0, 10).map((w) => `  ${w.launches}× ${w.workspace}`);
+        output.printBox([
+            `Launches (last hour): ${usage.lastHour}/${limits.maxLaunchesPerHour}`,
+            `Launches (last 24h):  ${usage.lastDay}/${limits.maxLaunchesPerDay}`,
+            `Active Claude children: ${usage.active}/${limits.maxConcurrentGlobal}`,
+            usage.pausedUntil
+                ? output.warning(`PAUSED until ${new Date(usage.pausedUntil).toISOString()} (${usage.pauseReason ?? 'quota error'})`)
+                : `Circuit breaker: ${output.dim('closed (normal)')}`,
+            ...(byWs.length > 0 ? ['Launches by workspace (24h):', ...byWs] : []),
+        ].join('\n'), 'Global AI Budget');
+        return { success: true, data: { usage, limits } };
+    },
+};
+const budgetPauseCommand = {
+    name: 'pause',
+    description: 'Pause ALL autonomous Claude launches across every daemon until resumed',
+    options: [
+        { name: 'reason', short: 'r', type: 'string', description: 'Optional reason recorded in the pause receipt' },
+    ],
+    examples: [{ command: 'claude-flow daemon budget pause --reason "conserving quota for a demo"', description: 'Pause autonomous launches' }],
+    action: async (ctx) => {
+        const { getGlobalAiBudget } = await import('../services/global-ai-budget.js');
+        await getGlobalAiBudget().pause(ctx.flags.reason);
+        output.printSuccess('Autonomous AI worker launches paused across all daemons. Resume with: ruflo daemon budget resume');
+        return { success: true };
+    },
+};
+const budgetResumeCommand = {
+    name: 'resume',
+    description: 'Resume autonomous Claude launches (clears a manual pause or a quota-triggered circuit-breaker pause)',
+    options: [],
+    examples: [{ command: 'claude-flow daemon budget resume', description: 'Resume autonomous launches' }],
+    action: async () => {
+        const { getGlobalAiBudget } = await import('../services/global-ai-budget.js');
+        await getGlobalAiBudget().resume();
+        output.printSuccess('Autonomous AI worker launches resumed.');
+        return { success: true };
+    },
+};
+const budgetCommand = {
+    name: 'budget',
+    description: 'Inspect and control the user-global AI launch budget (#2661)',
+    subcommands: [budgetShowCommand, budgetPauseCommand, budgetResumeCommand],
+    options: [],
+    examples: [
+        { command: 'claude-flow daemon budget show', description: 'Show current usage/limits' },
+        { command: 'claude-flow daemon budget pause', description: 'Pause all autonomous launches' },
+        { command: 'claude-flow daemon budget resume', description: 'Resume autonomous launches' },
+    ],
+    // Bare `daemon budget` (no subcommand) shows usage — same as `show`.
+    action: async (ctx) => {
+        const result = await budgetShowCommand.action(ctx);
+        return result ?? { success: true };
+    },
+};
 // Main daemon command
 export const daemonCommand = {
     name: 'daemon',
@@ -1506,6 +1677,7 @@ export const daemonCommand = {
         statusCommand,
         triggerCommand,
         enableCommand,
+        budgetCommand,
         installSupervisorCommand,
         uninstallSupervisorCommand,
     ],

package/v3/@claude-flow/cli/dist/src/init/statusline-generator.js

@@ -9,7 +9,50 @@
  * - Shared settings cache
  * - Strict 2s timeouts on all shell calls
  */
-import { getInstalledCliVersion } from './helper-refresh.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+const __dirname_sg = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolves the running CLI's own version — same createRequire/walk-up
+ * approach as helper-refresh.ts's getInstalledCliVersion(), duplicated
+ * here rather than imported. helper-refresh.ts pulls in the `semver`
+ * package at module scope (for autoRefreshHelpersIfStale()'s version
+ * comparison, unrelated to this) — ES module imports load a module's
+ * ENTIRE top-level regardless of which export is used, so importing just
+ * getInstalledCliVersion from there still requires `semver` to be resolvable.
+ * Confirmed live: the CI smoke job that loads this generator via a minimal
+ * "smoke deps" install (no full `npm install`) failed with
+ * ERR_MODULE_NOT_FOUND('semver') the moment this file gained that import,
+ * even though this function itself never touches semver. Keeping this
+ * generator's own dependency footprint to bare Node builtins avoids
+ * dragging every future helper-refresh.ts dependency into every context
+ * that merely wants to render a statusline script.
+ */
+function getInstalledCliVersionLocal() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(esmRequire.resolve('@claude-flow/cli/package.json'), 'utf-8'));
+        return String(pkg.version || '0.0.0');
+    }
+    catch {
+        let dir = __dirname_sg;
+        for (let i = 0; i < 6; i++) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+                if (pkg && pkg.name === '@claude-flow/cli')
+                    return String(pkg.version || '0.0.0');
+            }
+            catch { /* no package.json here, or unreadable — keep climbing */ }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return '0.0.0';
+    }
+}
 /**
  * Generate optimized statusline script
  * Output format:
@@ -33,7 +76,7 @@ export function generateStatuslineScript(options) {
     // previous hardcoded "3.6" placeholder. getPkgVersion()'s own runtime
     // candidate scan still wins over this baked-in value when it finds
     // something newer (e.g. a later `npm update` in the same project).
-    const bakedVersion = getInstalledCliVersion();
+    const bakedVersion = getInstalledCliVersionLocal();
     return `#!/usr/bin/env node
 /**
  * RuFlo V3 Statusline — delegation build (#2195)

package/v3/@claude-flow/cli/dist/src/services/global-ai-budget.d.ts

@@ -80,6 +80,31 @@ export declare class GlobalAiBudget {
      * daemon pauses ALL autonomous Claude launches for the cooldown window.
      */
     recordQuotaError(detail: string): Promise<void>;
+    /**
+     * #2661 root-fix — manual pause, via `ruflo daemon budget pause`. Distinct
+     * from the automatic quota-error circuit breaker only in duration (open-
+     * ended, until explicitly resumed, instead of a fixed cooldown) and
+     * reason text — the enforcement path in reserve() is identical, so a
+     * manual pause is just as hard a stop as a quota-triggered one.
+     */
+    pause(reason?: string): Promise<void>;
+    /** #2661 root-fix — `ruflo daemon budget resume`. Clears ANY pause (manual or quota-triggered). */
+    resume(): Promise<void>;
+    /**
+     * #2661 root-fix — structured per-launch token telemetry. Best-effort,
+     * receipt-only: usage is recorded as a distinct receipt keyed by permitId
+     * rather than mutated into the launch ledger, so a usage-recording failure
+     * can never corrupt the budget-enforcement ledger. Only operational
+     * metadata — never prompts or source content.
+     */
+    recordUsage(permitId: string | undefined, usage: {
+        workerType: string;
+        model: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        durationMs?: number;
+        costUsd?: number;
+    }): void;
     /** Snapshot for `daemon status` / diagnostics. */
     getUsage(): {
         lastHour: number;

package/v3/@claude-flow/cli/dist/src/services/global-ai-budget.js

@@ -221,6 +221,62 @@ export class GlobalAiBudget {
             unlock?.();
         }
     }
+    /**
+     * #2661 root-fix — manual pause, via `ruflo daemon budget pause`. Distinct
+     * from the automatic quota-error circuit breaker only in duration (open-
+     * ended, until explicitly resumed, instead of a fixed cooldown) and
+     * reason text — the enforcement path in reserve() is identical, so a
+     * manual pause is just as hard a stop as a quota-triggered one.
+     */
+    async pause(reason) {
+        let unlock = null;
+        try {
+            unlock = await this.acquireLock();
+            const now = Date.now();
+            const ledger = this.readLedger(now);
+            // Sentinel far-future timestamp rather than a real duration — resume()
+            // is the only thing that clears it. year ~2255, safely beyond any
+            // realistic process lifetime, and still a valid finite JS timestamp.
+            ledger.pausedUntil = 9_000_000_000_000;
+            ledger.pauseReason = (reason ?? 'manual pause (ruflo daemon budget pause)').slice(0, 200);
+            this.writeLedger(ledger);
+            this.appendReceipt({ event: 'manual-pause', at: now, reason: ledger.pauseReason });
+        }
+        finally {
+            unlock?.();
+        }
+    }
+    /** #2661 root-fix — `ruflo daemon budget resume`. Clears ANY pause (manual or quota-triggered). */
+    async resume() {
+        let unlock = null;
+        try {
+            unlock = await this.acquireLock();
+            const now = Date.now();
+            const ledger = this.readLedger(now);
+            const wasPaused = ledger.pausedUntil !== undefined && ledger.pausedUntil > now;
+            ledger.pausedUntil = undefined;
+            ledger.pauseReason = undefined;
+            this.writeLedger(ledger);
+            if (wasPaused) {
+                this.appendReceipt({ event: 'manual-resume', at: now });
+            }
+        }
+        finally {
+            unlock?.();
+        }
+    }
+    /**
+     * #2661 root-fix — structured per-launch token telemetry. Best-effort,
+     * receipt-only: usage is recorded as a distinct receipt keyed by permitId
+     * rather than mutated into the launch ledger, so a usage-recording failure
+     * can never corrupt the budget-enforcement ledger. Only operational
+     * metadata — never prompts or source content.
+     */
+    recordUsage(permitId, usage) {
+        if (!permitId || permitId.startsWith('bypass_'))
+            return;
+        this.appendReceipt({ event: 'usage', at: Date.now(), permitId, ...usage });
+    }
     /** Snapshot for `daemon status` / diagnostics. */
     getUsage() {
         try {

package/v3/@claude-flow/cli/dist/src/services/headless-worker-executor.d.ts

@@ -119,6 +119,10 @@ export interface HeadlessExecutionResult {
     durationMs: number;
     /** Estimated tokens used (if available) */
     tokensUsed?: number;
+    /** #2661 root-fix — structured usage, when `claude --print --output-format json` exposed it. */
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
     /** Model used for execution */
     model: string;
     /** Sandbox mode used */
@@ -190,6 +194,23 @@ export declare function isLocalWorker(type: WorkerType): type is LocalWorkerType
  * Get model ID from model type
  */
 export declare function getModelId(model: ModelType): string;
+export interface ClaudePrintEnvelope {
+    result: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    durationMs?: number;
+}
+/**
+ * #2661 root-fix — best-effort parse of `claude --print --output-format
+ * json`'s response envelope. Deliberately lenient: probes a couple of
+ * plausible field-name shapes (the CLI's JSON schema is not a versioned
+ * public contract) and returns null on anything unexpected rather than
+ * throwing, so a schema mismatch degrades to "no usage captured" — the
+ * caller then falls back to the raw stdout text, exactly today's behavior.
+ * Exported for direct unit testing without spawning a real process.
+ */
+export declare function parseClaudePrintJsonEnvelope(raw: string): ClaudePrintEnvelope | null;
 /**
  * Get worker configuration by type
  */