claude-flow 3.26.1 → 3.27.0

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

@@ -15,79 +15,9 @@
 
 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).
-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) {
-      if (fs.existsSync(p)) return p;
-    }
-  } 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.
-function spawnDetachedFunnelRefresh() {
-  try {
-    const cliBin = resolveCliBinForHook();
-    if (!cliBin) return;
-    const { spawn } = require('child_process');
-    const child = spawn(process.execPath, [cliBin, 'hooks', 'refresh-funnel', '--quiet'], {
-      detached: true,
-      stdio: 'ignore',
-      env: process.env,
-    });
-    child.unref();
-  } catch (e) { /* best-effort only */ }
-}
-
-// Same detached/unref'd 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() {
-  try {
-    const cliBin = resolveCliBinForHook();
-    if (!cliBin) return;
-    const { spawn } = require('child_process');
-    const child = spawn(process.execPath, [cliBin, 'hooks', 'refresh-advisor', '--quiet'], {
-      detached: true,
-      stdio: 'ignore',
-      env: process.env,
-    });
-    child.unref();
-  } catch (e) { /* best-effort only */ }
-}
-
 // 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.
@@ -238,57 +168,6 @@ 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': () => {
@@ -355,14 +234,6 @@ 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,16 +587,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.26.1",
+  "version": "3.27.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-13T17:21:15.123Z",
-  "gitSha": "eabf9530",
+  "generatedAt": "2026-07-14T03:21:11.654Z",
+  "gitSha": "87212ddb",
   "catalog": {
     "agents": 164,
     "tools": 387,

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

@@ -23,7 +23,11 @@ const startCommand = {
         { name: 'quiet', short: 'Q', type: 'boolean', description: 'Suppress output' },
         { name: 'background', short: 'b', type: 'boolean', description: 'Run daemon in background (detached process)', default: true },
         { name: 'foreground', short: 'f', type: 'boolean', description: 'Run daemon in foreground (blocks terminal)' },
-        { name: 'headless', type: 'boolean', description: 'Enable headless worker execution (E2B sandbox)' },
+        // #2661: --headless is the explicit consent gate for scheduled AI workers.
+        // Without it (or daemon.aiWorkers.enabled / RUFLO_DAEMON_AI_WORKERS=1),
+        // every worker runs its $0 local path — the daemon never spawns
+        // `claude --print` merely because the Claude CLI is on PATH.
+        { name: 'headless', type: 'boolean', description: 'Enable AI workers (scheduled `claude --print` execution, governed by the user-global AI budget). Default: off — workers run local-only' },
         { name: 'sandbox', type: 'string', description: 'Default sandbox mode for headless workers', choices: ['strict', 'permissive', 'disabled'] },
         { name: 'max-cpu-load', type: 'string', description: 'Override maxCpuLoad resource threshold (e.g. 4.0)' },
         { name: 'min-free-memory', type: 'string', description: 'Override minFreeMemoryPercent resource threshold (e.g. 15)' },
@@ -60,6 +64,14 @@ const startCommand = {
         const isDaemonProcess = process.env.CLAUDE_FLOW_DAEMON === '1';
         // Parse resource threshold overrides from CLI flags
         const config = {};
+        // #2661: thread --headless into DaemonConfig so it actually gates the
+        // headless executor. Previously the flag was forwarded to the forked
+        // child but never consumed — AI workers auto-enabled whenever the
+        // Claude CLI was detected. Only set when true so config.json/env can
+        // still opt in when the flag is absent.
+        if (ctx.flags.headless === true) {
+            config.aiWorkersEnabled = true;
+        }
         const rawMaxCpu = ctx.flags['max-cpu-load'];
         const rawMinMem = ctx.flags['min-free-memory'];
         // Strict numeric pattern to prevent command injection when forwarding to subprocess (S1)
@@ -296,6 +308,7 @@ const startCommand = {
                     status.config.ttlMs > 0
                         ? `TTL: ${Math.round(status.config.ttlMs / 3600000)}h (self-shutdown)`
                         : `TTL: off (runs until stopped)`,
+                    `AI Workers: ${status.config.aiWorkersEnabled ? 'enabled (budget-capped)' : 'off (local-only, default)'}`,
                     `Workers: ${status.config.workers.filter(w => w.enabled).length} enabled`,
                     `Max Concurrent: ${status.config.maxConcurrent}`,
                     `Max CPU Load: ${status.config.resourceThresholds.maxCpuLoad}`,
@@ -552,6 +565,21 @@ async function startBackgroundDaemon(projectRoot, quiet, forwarded = {}) {
         output.printSuccess(`Daemon started in background (PID: ${pid})`);
         output.printInfo(`Logs: ${logFile}`);
         output.printInfo(`Stop with: claude-flow daemon stop`);
+        // #2661: worktree-fanout warning. Each Git worktree gets its own daemon
+        // (per-workspace scope, #1914), so `init --start-daemon` across N
+        // worktrees quietly accumulates N daemons. Surface the fleet size at
+        // start time so the accumulation is visible where it happens.
+        try {
+            const fleet = await scanRunningDaemons();
+            if (fleet.length > 1) {
+                output.writeln();
+                output.printWarning(`Found ${fleet.length} ruflo daemons running across workspaces/worktrees.`);
+                output.printInfo('Scheduled AI workers are off by default and every AI launch is capped by the user-global budget.');
+                output.printInfo('Inspect:  ruflo daemon status --all');
+                output.printInfo('Stop all: ruflo daemon stop --all');
+            }
+        }
+        catch { /* best-effort visibility — never fail the start */ }
     }
     return { success: true };
 }
@@ -561,13 +589,24 @@ const stopCommand = {
     description: 'Stop the worker daemon and all background workers',
     options: [
         { name: 'quiet', short: 'Q', type: 'boolean', description: 'Suppress output' },
+        // #2661: emergency stop for worktree-daemon fleets. Stops every ruflo
+        // daemon owned by the current user across ALL workspaces/worktrees.
+        { name: 'all', short: 'a', type: 'boolean', description: 'Stop ruflo daemons in ALL workspaces/worktrees (not just the current one)' },
     ],
     examples: [
-        { command: 'claude-flow daemon stop', description: 'Stop the daemon' },
+        { command: 'claude-flow daemon stop', description: 'Stop the daemon in this workspace' },
+        { command: 'claude-flow daemon stop --all', description: 'Stop ruflo daemons in every workspace/worktree' },
     ],
     action: async (ctx) => {
         const quiet = ctx.flags.quiet;
         const projectRoot = process.cwd();
+        // #2661: `stop --all` — the containment lever for daemon fanout across
+        // Git worktrees. Only processes positively identified as ruflo daemons
+        // (via their self-identifying argv) are touched; each receives SIGTERM
+        // so its own shutdown path reaps in-flight Claude process groups.
+        if (ctx.flags.all) {
+            return stopAllDaemons(quiet);
+        }
         try {
             if (!quiet) {
                 const spinner = output.createSpinner({ text: 'Stopping worker daemon...', spinner: 'dots' });
@@ -593,6 +632,81 @@ const stopCommand = {
         }
     },
 };
+/**
+ * #2661: stop every running ruflo daemon across all workspaces/worktrees.
+ *
+ * Reuses the same positive identification as `daemon status --all`
+ * (scanRunningDaemons): a process is only touched when its command line is
+ * self-identifying as a ruflo daemon (`daemon start --foreground` +
+ * claude-flow markers). Interactive Claude sessions and non-ruflo processes
+ * are never candidates. Each daemon gets SIGTERM first — its own shutdown
+ * handler cancels in-flight headless Claude process groups and removes its
+ * PID file — with a SIGKILL fallback for daemons that don't exit within 2s.
+ * Only ruflo-owned registry entries (each workspace's daemon.pid) are removed.
+ */
+async function stopAllDaemons(quiet) {
+    // Stop any in-process daemon plus this workspace's tracked daemon first,
+    // matching plain `daemon stop` semantics for the current directory.
+    try {
+        await stopDaemon();
+    }
+    catch { /* not running in-process */ }
+    await killBackgroundDaemon(process.cwd());
+    const daemons = await scanRunningDaemons();
+    if (daemons.length === 0) {
+        if (!quiet) {
+            output.printInfo('No ruflo daemons are running in any workspace.');
+        }
+        return { success: true, data: { stopped: 0 } };
+    }
+    const isWin = process.platform === 'win32';
+    let stopped = 0;
+    for (const d of daemons) {
+        try {
+            if (isWin) {
+                const { execFileSync } = await import('child_process');
+                // /t terminates the daemon's child tree too (no /f: graceful first).
+                execFileSync('taskkill', ['/pid', String(d.pid), '/t'], { encoding: 'utf-8', timeout: 5000 });
+            }
+            else {
+                process.kill(d.pid, 'SIGTERM');
+            }
+            stopped++;
+            if (!quiet) {
+                output.printInfo(`Stopping daemon PID ${d.pid}${d.workspace ? ` (${d.workspace})` : ''}`);
+            }
+        }
+        catch { /* exited between scan and kill */ }
+    }
+    // Give SIGTERM handlers time to reap children and clean up, then
+    // force-kill anything still alive (POSIX; taskkill /t already recursed).
+    await new Promise((r) => setTimeout(r, 2000));
+    for (const d of daemons) {
+        if (!isWin && isProcessRunning(d.pid)) {
+            try {
+                process.kill(d.pid, 'SIGKILL');
+            }
+            catch { /* already dead */ }
+        }
+        // Remove the ruflo-owned PID file for that workspace — but only when it
+        // still points at the daemon we just stopped (never clobber a newer one).
+        if (d.workspace) {
+            try {
+                const pidFile = join(d.workspace, '.claude-flow', 'daemon.pid');
+                if (fs.existsSync(pidFile)) {
+                    const filePid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+                    if (filePid === d.pid)
+                        fs.unlinkSync(pidFile);
+                }
+            }
+            catch { /* workspace removed or unreadable — nothing to clean */ }
+        }
+    }
+    if (!quiet) {
+        output.printSuccess(`Stopped ${stopped} ruflo daemon(s) across all workspaces.`);
+    }
+    return { success: true, data: { stopped } };
+}
 /**
  * Kill background daemon process using PID file
  */
@@ -893,6 +1007,31 @@ async function renderAllDaemonsStatus() {
     else {
         output.printInfo(`${daemons.length} daemon(s) running, all within their TTL.`);
     }
+    if (daemons.length > 1) {
+        output.printInfo('Stop all daemons across workspaces with: ruflo daemon stop --all');
+    }
+    // #2661: user-global AI launch usage — the shared budget every daemon
+    // draws from, independent of worktree count.
+    try {
+        const { getGlobalAiBudget } = await import('../services/global-ai-budget.js');
+        const budget = getGlobalAiBudget();
+        const usage = budget.getUsage();
+        const limits = budget.getLimits();
+        output.writeln();
+        // #2661: per-workspace 24h launch attribution — which worktree is
+        // actually spending the shared budget.
+        const byWs = usage.byWorkspace.slice(0, 5).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 (all workspaces)');
+    }
+    catch { /* budget ledger unavailable — skip the panel */ }
     return { success: true, data: { daemons: rows.length } };
 }
 // Status subcommand
@@ -929,6 +1068,21 @@ const statusCommand = {
             const bgRunning = bgPid ? isProcessRunning(bgPid) : false;
             const isRunning = status.running || bgRunning;
             const displayPid = bgPid || status.pid;
+            // #2661: this CLI process constructs its own (default-config) daemon
+            // instance, so status.config.aiWorkersEnabled reflects THIS process,
+            // not the running background daemon. The background daemon persists
+            // its real consent state into daemon-state.json — prefer that when it
+            // is the one running.
+            let aiWorkersEnabled = status.config.aiWorkersEnabled;
+            if (bgRunning) {
+                try {
+                    const st = JSON.parse(fs.readFileSync(join(projectRoot, '.claude-flow', 'daemon-state.json'), 'utf-8'));
+                    if (typeof st?.config?.aiWorkersEnabled === 'boolean') {
+                        aiWorkersEnabled = st.config.aiWorkersEnabled;
+                    }
+                }
+                catch { /* no/partial state — fall back to in-process config */ }
+            }
             output.writeln();
             // Daemon status box
             const statusIcon = isRunning ? output.success('●') : output.error('○');
@@ -941,6 +1095,9 @@ const statusCommand = {
                 status.config.ttlMs > 0
                     ? `TTL: ${Math.round(status.config.ttlMs / 3600000)}h (self-shutdown)`
                     : `TTL: ${output.dim('off (runs until stopped)')}`,
+                // #2661: surface the AI-consent gate so "why is audit local-only?"
+                // is answerable from `daemon status` alone.
+                `AI Workers: ${aiWorkersEnabled ? output.warning('enabled (budget-capped)') : output.dim('off (local-only, default)')}`,
                 `Workers Enabled: ${status.config.workers.filter(w => w.enabled).length}`,
                 `Max Concurrent: ${status.config.maxConcurrent}`,
                 `Max CPU Load: ${status.config.resourceThresholds.maxCpuLoad}`,
@@ -1043,7 +1200,10 @@ const triggerCommand = {
             return { success: false, exitCode: 1 };
         }
         try {
-            const daemon = getDaemon(process.cwd());
+            // #2661: an explicit `trigger --headless` is user consent for AI
+            // execution of THIS run (still governed by the global AI budget).
+            // Without the flag, config.json / env opt-in still applies.
+            const daemon = getDaemon(process.cwd(), ctx.flags.headless === true ? { aiWorkersEnabled: true } : undefined);
             const spinner = output.createSpinner({ text: `Running ${workerType} worker...`, spinner: 'dots' });
             spinner.start();
             const result = await daemon.triggerWorker(workerType);

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

@@ -449,9 +449,39 @@ export function generateHookHandler() {
         "const path = require('path');",
         "const fs = require('fs');",
         "const os = require('os');",
+        "const { spawn } = require('child_process');",
         '',
         'const helpersDir = __dirname;',
         '',
+        // #2661-adjacent fix: `refreshRemoteMessages()` (the funnel promo/disclosure
+        // pool) is fire-and-forget by design so the statusline's own short-lived
+        // per-render subprocess never blocks on a network call — but that also
+        // means it NEVER gets a chance to finish there (confirmed live: two
+        // consecutive cold-cache statusline renders returned promo:null and no
+        // cache file was ever written). `refresh-funnel` exists specifically to
+        // be spawned from a longer-lived context; wire that spawn here, once per
+        // session, detached so it survives this hook process exiting and isn't
+        // awaited so it never adds to the hook's own timeout budget.
+        //
+        // Deliberately always via npx (--prefer-offline avoids a registry round
+        // trip when already cached), never a locally-resolved bin/cli.js path:
+        // a fire-and-forget detached spawn has no way to recover if the first
+        // candidate is a broken/unbuilt local install (confirmed live — a stale
+        // marketplace checkout with a bin/cli.js that exists but throws
+        // MODULE_NOT_FOUND on its own dist/ silently ate the spawn with no
+        // fallback and no visible error, since stdio is intentionally ignored).
+        // npx resolves a real, structurally-valid published package every time.
+        'function spawnFunnelRefresh() {',
+        '  try {',
+        "    var cmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';",
+        "    var args = ['--prefer-offline', '@claude-flow/cli', 'hooks', 'refresh-funnel', '--quiet'];",
+        '    var child = spawn(cmd, args, {',
+        "      detached: true, stdio: 'ignore', env: Object.assign({}, process.env),",
+        '    });',
+        '    child.unref();',
+        '  } catch (e) { /* best-effort — the statusline\'s own fallback still renders */ }',
+        '}',
+        '',
         'function safeRequire(modulePath) {',
         '  try {',
         '    if (fs.existsSync(modulePath)) {',
@@ -617,6 +647,7 @@ export function generateHookHandler() {
         '  },',
         '',
         "  'session-restore': () => {",
+        '    spawnFunnelRefresh();',
         '    if (session) {',
         '      var existing = session.restore && session.restore();',
         '      if (!existing) {',

package/v3/@claude-flow/cli/dist/src/services/ai-job-dedup.d.ts

@@ -0,0 +1,61 @@
+/**
+ * #2661 — Cross-worktree AI job dedup (issue invariant 5).
+ *
+ * N worktrees of one repository checked out at the same HEAD schedule the
+ * same analyses independently: N audits of identical content, N optimize
+ * passes, N testgap sweeps. Before a model launch, callers compute
+ *
+ *   jobKey = sha256(repositoryId, head, workerType, workerConfigHash)
+ *
+ * and skip the launch when the same job succeeded within the freshness
+ * window. HEAD moves → new key → the job runs again.
+ *
+ * The registry lives next to the AI budget ledger under the user's home
+ * directory (owner-only, symlink-rejecting) so all daemons share it:
+ *
+ *   ~/.claude-flow/ai-jobs.json
+ *
+ * This is a best-effort OPTIMIZATION layered under the budget: two daemons
+ * racing the same key may both miss and both attempt a launch, but the
+ * budget's atomic reservation (maxConcurrentGlobal / hourly cap) is the hard
+ * invariant that bounds actual launches. Only operational metadata is
+ * persisted — never prompts, outputs, or source content.
+ */
+export interface AiJobKeyParts {
+    repositoryId: string;
+    head: string;
+    workerType: string;
+    /** Hash of the effective worker config (prompt/model/sandbox/patterns). */
+    configHash: string;
+}
+export declare function computeAiJobKey(parts: AiJobKeyParts): string;
+/** Stable hash of an arbitrary config object (key-sorted JSON). */
+export declare function hashWorkerConfig(config: unknown): string;
+export declare class AiJobDedupRegistry {
+    private readonly dir;
+    private readonly file;
+    constructor(options?: {
+        baseDir?: string;
+    });
+    /**
+     * True when the job succeeded within `freshnessMs`. Any registry error
+     * reads as "not fresh" — dedup failing open only costs a (budget-capped)
+     * launch, never correctness.
+     */
+    isFresh(jobKey: string, freshnessMs: number): {
+        fresh: boolean;
+        lastRunAt?: number;
+    };
+    /** Record a successful run of a job. Best-effort. */
+    recordSuccess(jobKey: string, meta: {
+        workerType: string;
+        repositoryId: string;
+        workspace: string;
+    }): void;
+    private read;
+    private write;
+}
+export declare function getAiJobDedupRegistry(): AiJobDedupRegistry;
+/** Test hook: reset the singleton (e.g. after changing RUFLO_AI_BUDGET_DIR). */
+export declare function resetAiJobDedupRegistryForTests(): void;
+//# sourceMappingURL=ai-job-dedup.d.ts.map