@claude-flow/cli 3.26.1 → 3.27.0

package/dist/src/services/global-ai-budget.d.ts

@@ -0,0 +1,110 @@
+/**
+ * #2661 — Global AI launch budget (emergency cost fuse).
+ *
+ * Every autonomous `claude --print` launch across ALL ruflo daemons in ALL
+ * worktrees/workspaces owned by the current user must pass through this
+ * user-global budget before a process is created. Without it, N worktree
+ * daemons each schedule their own AI workers and aggregate launch volume
+ * scales linearly with worktree count — enough to exhaust a user's Claude
+ * hourly quota silently (13 launches/hour/daemon under the legacy schedule).
+ *
+ * The ledger lives under the user's home directory (NOT the workspace) so
+ * daemons started from different worktrees of the same repository — or from
+ * unrelated repositories — all share one budget:
+ *
+ *   ~/.claude-flow/ai-budget.json           launch ledger + circuit breaker
+ *   ~/.claude-flow/ai-budget.lock           O_EXCL mutation lock
+ *   ~/.claude-flow/ai-budget-receipts.jsonl launch/deny/pause receipts
+ *
+ * Files are owner-only (0700 dir / 0600 files) and symlinks are rejected
+ * (invariant 9 of #2661). All checks happen BEFORE process creation and the
+ * ledger mutation is atomic under the lock, so two daemons racing for the
+ * last hourly slot cannot both win.
+ *
+ * Default limits (issue #2661 containment):
+ *   maxConcurrentGlobal      1   at most one autonomous claude child, user-wide
+ *   maxLaunchesPerHour       2
+ *   maxLaunchesPerDay        12
+ *   pauseOnQuotaErrorMinutes 60  circuit breaker on 429/quota responses
+ */
+export interface AiBudgetLimits {
+    maxConcurrentGlobal: number;
+    maxLaunchesPerHour: number;
+    maxLaunchesPerDay: number;
+    pauseOnQuotaErrorMinutes: number;
+}
+export declare const DEFAULT_AI_BUDGET_LIMITS: AiBudgetLimits;
+export interface AiBudgetRequest {
+    workerType: string;
+    model: string;
+    /** Worktree/workspace root requesting the launch (recorded for receipts only). */
+    workspace: string;
+}
+export interface AiBudgetPermit {
+    allowed: boolean;
+    permitId?: string;
+    reason?: string;
+}
+/**
+ * Heuristic match for Anthropic quota / rate-limit failures. Only ever
+ * applied to ERROR output of a FAILED launch (never to successful analysis
+ * output, which may legitimately discuss "rate limiting" in the user's code).
+ */
+export declare function isQuotaErrorText(text: string | undefined): boolean;
+export declare class GlobalAiBudget {
+    private readonly dir;
+    private readonly ledgerFile;
+    private readonly lockFile;
+    private readonly receiptsFile;
+    private readonly limits;
+    constructor(options?: {
+        baseDir?: string;
+        limits?: Partial<AiBudgetLimits>;
+    });
+    getLimits(): AiBudgetLimits;
+    /**
+     * Atomically reserve one launch slot. Denials carry a machine-readable
+     * reason and are receipted. The reservation is counted as a launch
+     * immediately (the hourly/daily invariant is on launches, not completions);
+     * `release()` only frees the concurrency slot.
+     *
+     * Fails CLOSED: if the ledger cannot be read or locked, the launch is
+     * denied — an unaccountable launch is exactly what this fuse exists to
+     * prevent. `RUFLO_AI_BUDGET_DISABLE=1` is the explicit escape hatch.
+     */
+    reserve(req: AiBudgetRequest): Promise<AiBudgetPermit>;
+    /** Free the concurrency slot held by a permit. Best-effort. */
+    release(permitId: string | undefined): Promise<void>;
+    /**
+     * Open the user-global circuit breaker: a quota/429 response from ANY
+     * daemon pauses ALL autonomous Claude launches for the cooldown window.
+     */
+    recordQuotaError(detail: string): Promise<void>;
+    /** Snapshot for `daemon status` / diagnostics. */
+    getUsage(): {
+        lastHour: number;
+        lastDay: number;
+        active: number;
+        pausedUntil?: number;
+        pauseReason?: string;
+        /** #2661 — 24h launch counts per worktree/workspace, most active first. */
+        byWorkspace: Array<{
+            workspace: string;
+            launches: number;
+        }>;
+    };
+    private ensureDir;
+    private acquireLock;
+    /** Read + prune the ledger. Caller must hold the lock for read-modify-write. */
+    private readLedger;
+    private writeLedger;
+    /**
+     * Invariant 10: every launch, denial, and pause emits a receipt. Only
+     * operational metadata is persisted — never prompts or source content.
+     */
+    private appendReceipt;
+}
+export declare function getGlobalAiBudget(): GlobalAiBudget;
+/** Test hook: reset the singleton (e.g. after changing RUFLO_AI_BUDGET_DIR). */
+export declare function resetGlobalAiBudgetForTests(): void;
+//# sourceMappingURL=global-ai-budget.d.ts.map

package/dist/src/services/global-ai-budget.js

@@ -0,0 +1,359 @@
+/**
+ * #2661 — Global AI launch budget (emergency cost fuse).
+ *
+ * Every autonomous `claude --print` launch across ALL ruflo daemons in ALL
+ * worktrees/workspaces owned by the current user must pass through this
+ * user-global budget before a process is created. Without it, N worktree
+ * daemons each schedule their own AI workers and aggregate launch volume
+ * scales linearly with worktree count — enough to exhaust a user's Claude
+ * hourly quota silently (13 launches/hour/daemon under the legacy schedule).
+ *
+ * The ledger lives under the user's home directory (NOT the workspace) so
+ * daemons started from different worktrees of the same repository — or from
+ * unrelated repositories — all share one budget:
+ *
+ *   ~/.claude-flow/ai-budget.json           launch ledger + circuit breaker
+ *   ~/.claude-flow/ai-budget.lock           O_EXCL mutation lock
+ *   ~/.claude-flow/ai-budget-receipts.jsonl launch/deny/pause receipts
+ *
+ * Files are owner-only (0700 dir / 0600 files) and symlinks are rejected
+ * (invariant 9 of #2661). All checks happen BEFORE process creation and the
+ * ledger mutation is atomic under the lock, so two daemons racing for the
+ * last hourly slot cannot both win.
+ *
+ * Default limits (issue #2661 containment):
+ *   maxConcurrentGlobal      1   at most one autonomous claude child, user-wide
+ *   maxLaunchesPerHour       2
+ *   maxLaunchesPerDay        12
+ *   pauseOnQuotaErrorMinutes 60  circuit breaker on 429/quota responses
+ */
+import * as fs from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+export const DEFAULT_AI_BUDGET_LIMITS = {
+    maxConcurrentGlobal: 1,
+    maxLaunchesPerHour: 2,
+    maxLaunchesPerDay: 12,
+    pauseOnQuotaErrorMinutes: 60,
+};
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+// Active reservations older than this are treated as abandoned (crashed
+// daemon). Must exceed the daemon's 16-min worker timeout with margin.
+const ACTIVE_STALE_MS = 30 * 60 * 1000;
+// A mutation lock older than this belongs to a crashed process — take it over.
+const LOCK_STALE_MS = 10_000;
+const RECEIPTS_MAX_BYTES = 512 * 1024;
+const RECEIPTS_KEEP_LINES = 200;
+/**
+ * Heuristic match for Anthropic quota / rate-limit failures. Only ever
+ * applied to ERROR output of a FAILED launch (never to successful analysis
+ * output, which may legitimately discuss "rate limiting" in the user's code).
+ */
+export function isQuotaErrorText(text) {
+    if (!text)
+        return false;
+    return /\b429\b|rate[\s_-]?limit|usage[\s_-]?limit|quota|too many requests|overloaded_error/i.test(text);
+}
+function envPositiveInt(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Invariant 9: registry files must never be symlinks. */
+function assertNotSymlink(path) {
+    try {
+        const st = fs.lstatSync(path);
+        if (st.isSymbolicLink()) {
+            throw new Error(`AI budget file is a symlink (refusing): ${path}`);
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export class GlobalAiBudget {
+    dir;
+    ledgerFile;
+    lockFile;
+    receiptsFile;
+    limits;
+    constructor(options) {
+        this.dir = options?.baseDir
+            ?? process.env.RUFLO_AI_BUDGET_DIR
+            ?? join(homedir(), '.claude-flow');
+        this.ledgerFile = join(this.dir, 'ai-budget.json');
+        this.lockFile = join(this.dir, 'ai-budget.lock');
+        this.receiptsFile = join(this.dir, 'ai-budget-receipts.jsonl');
+        this.limits = {
+            maxConcurrentGlobal: options?.limits?.maxConcurrentGlobal
+                ?? envPositiveInt('RUFLO_AI_MAX_CONCURRENT')
+                ?? DEFAULT_AI_BUDGET_LIMITS.maxConcurrentGlobal,
+            maxLaunchesPerHour: options?.limits?.maxLaunchesPerHour
+                ?? envPositiveInt('RUFLO_AI_MAX_PER_HOUR')
+                ?? DEFAULT_AI_BUDGET_LIMITS.maxLaunchesPerHour,
+            maxLaunchesPerDay: options?.limits?.maxLaunchesPerDay
+                ?? envPositiveInt('RUFLO_AI_MAX_PER_DAY')
+                ?? DEFAULT_AI_BUDGET_LIMITS.maxLaunchesPerDay,
+            pauseOnQuotaErrorMinutes: options?.limits?.pauseOnQuotaErrorMinutes
+                ?? envPositiveInt('RUFLO_AI_QUOTA_PAUSE_MINUTES')
+                ?? DEFAULT_AI_BUDGET_LIMITS.pauseOnQuotaErrorMinutes,
+        };
+    }
+    getLimits() {
+        return { ...this.limits };
+    }
+    /**
+     * Atomically reserve one launch slot. Denials carry a machine-readable
+     * reason and are receipted. The reservation is counted as a launch
+     * immediately (the hourly/daily invariant is on launches, not completions);
+     * `release()` only frees the concurrency slot.
+     *
+     * Fails CLOSED: if the ledger cannot be read or locked, the launch is
+     * denied — an unaccountable launch is exactly what this fuse exists to
+     * prevent. `RUFLO_AI_BUDGET_DISABLE=1` is the explicit escape hatch.
+     */
+    async reserve(req) {
+        if (process.env.RUFLO_AI_BUDGET_DISABLE === '1') {
+            return { allowed: true, permitId: `bypass_${Date.now()}_${process.pid}` };
+        }
+        let unlock = null;
+        try {
+            unlock = await this.acquireLock();
+            const now = Date.now();
+            const ledger = this.readLedger(now);
+            let reason = null;
+            if (ledger.pausedUntil && ledger.pausedUntil > now) {
+                reason = `circuit-open until ${new Date(ledger.pausedUntil).toISOString()} (${ledger.pauseReason ?? 'quota error'})`;
+            }
+            else if (ledger.active.length >= this.limits.maxConcurrentGlobal) {
+                reason = `global-concurrency (${ledger.active.length}/${this.limits.maxConcurrentGlobal} active)`;
+            }
+            else {
+                const lastHour = ledger.launches.filter((l) => now - l.at < HOUR_MS).length;
+                const lastDay = ledger.launches.length; // already pruned to 24h
+                if (lastHour >= this.limits.maxLaunchesPerHour) {
+                    reason = `hourly-budget (${lastHour}/${this.limits.maxLaunchesPerHour} in last hour)`;
+                }
+                else if (lastDay >= this.limits.maxLaunchesPerDay) {
+                    reason = `daily-budget (${lastDay}/${this.limits.maxLaunchesPerDay} in last 24h)`;
+                }
+            }
+            if (reason) {
+                this.appendReceipt({ event: 'deny', at: now, reason, ...req });
+                return { allowed: false, reason };
+            }
+            const permitId = `permit_${now}_${process.pid}_${Math.random().toString(36).slice(2, 8)}`;
+            ledger.launches.push({ at: now, pid: process.pid, workerType: req.workerType, model: req.model, workspace: req.workspace });
+            ledger.active.push({ permitId, at: now, pid: process.pid, workerType: req.workerType });
+            this.writeLedger(ledger);
+            this.appendReceipt({ event: 'launch', at: now, permitId, ...req });
+            return { allowed: true, permitId };
+        }
+        catch (e) {
+            // Fail closed — see docstring.
+            const reason = `budget-ledger-error: ${e instanceof Error ? e.message : String(e)}`;
+            try {
+                this.appendReceipt({ event: 'deny', at: Date.now(), reason, ...req });
+            }
+            catch { /* best-effort */ }
+            return { allowed: false, reason };
+        }
+        finally {
+            unlock?.();
+        }
+    }
+    /** Free the concurrency slot held by a permit. Best-effort. */
+    async release(permitId) {
+        if (!permitId || permitId.startsWith('bypass_'))
+            return;
+        let unlock = null;
+        try {
+            unlock = await this.acquireLock();
+            const ledger = this.readLedger(Date.now());
+            const before = ledger.active.length;
+            ledger.active = ledger.active.filter((a) => a.permitId !== permitId);
+            if (ledger.active.length !== before)
+                this.writeLedger(ledger);
+        }
+        catch {
+            // Abandoned reservations expire via ACTIVE_STALE_MS pruning.
+        }
+        finally {
+            unlock?.();
+        }
+    }
+    /**
+     * Open the user-global circuit breaker: a quota/429 response from ANY
+     * daemon pauses ALL autonomous Claude launches for the cooldown window.
+     */
+    async recordQuotaError(detail) {
+        let unlock = null;
+        try {
+            unlock = await this.acquireLock();
+            const now = Date.now();
+            const ledger = this.readLedger(now);
+            ledger.pausedUntil = now + this.limits.pauseOnQuotaErrorMinutes * 60 * 1000;
+            ledger.pauseReason = detail.slice(0, 200);
+            this.writeLedger(ledger);
+            this.appendReceipt({ event: 'quota-pause', at: now, until: ledger.pausedUntil, detail: ledger.pauseReason });
+        }
+        catch {
+            // best-effort — the hourly budget still bounds retries
+        }
+        finally {
+            unlock?.();
+        }
+    }
+    /** Snapshot for `daemon status` / diagnostics. */
+    getUsage() {
+        try {
+            const now = Date.now();
+            const ledger = this.readLedger(now);
+            const byWs = new Map();
+            for (const l of ledger.launches) {
+                byWs.set(l.workspace, (byWs.get(l.workspace) ?? 0) + 1);
+            }
+            return {
+                lastHour: ledger.launches.filter((l) => now - l.at < HOUR_MS).length,
+                lastDay: ledger.launches.length,
+                active: ledger.active.length,
+                pausedUntil: ledger.pausedUntil && ledger.pausedUntil > now ? ledger.pausedUntil : undefined,
+                pauseReason: ledger.pausedUntil && ledger.pausedUntil > now ? ledger.pauseReason : undefined,
+                byWorkspace: Array.from(byWs.entries())
+                    .map(([workspace, launches]) => ({ workspace, launches }))
+                    .sort((a, b) => b.launches - a.launches),
+            };
+        }
+        catch {
+            return { lastHour: 0, lastDay: 0, active: 0, byWorkspace: [] };
+        }
+    }
+    // -- internals ----------------------------------------------------------
+    ensureDir() {
+        if (!fs.existsSync(this.dir)) {
+            fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        }
+    }
+    async acquireLock() {
+        this.ensureDir();
+        const deadline = Date.now() + 2000;
+        for (;;) {
+            try {
+                const fd = fs.openSync(this.lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+                fs.writeSync(fd, String(process.pid));
+                fs.closeSync(fd);
+                return () => {
+                    try {
+                        fs.unlinkSync(this.lockFile);
+                    }
+                    catch { /* already gone */ }
+                };
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+                // Stale lock from a crashed process — take over.
+                try {
+                    const st = fs.lstatSync(this.lockFile);
+                    if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                        fs.unlinkSync(this.lockFile);
+                        continue;
+                    }
+                }
+                catch { /* raced — retry */ }
+                if (Date.now() > deadline) {
+                    throw new Error('timed out acquiring ai-budget lock');
+                }
+                await delay(25);
+            }
+        }
+    }
+    /** Read + prune the ledger. Caller must hold the lock for read-modify-write. */
+    readLedger(now) {
+        assertNotSymlink(this.ledgerFile);
+        let ledger = { version: 1, launches: [], active: [] };
+        if (fs.existsSync(this.ledgerFile)) {
+            try {
+                const raw = JSON.parse(fs.readFileSync(this.ledgerFile, 'utf-8'));
+                if (raw && typeof raw === 'object') {
+                    ledger = {
+                        version: 1,
+                        launches: Array.isArray(raw.launches) ? raw.launches.filter((l) => typeof l?.at === 'number') : [],
+                        active: Array.isArray(raw.active) ? raw.active.filter((a) => typeof a?.at === 'number') : [],
+                        pausedUntil: typeof raw.pausedUntil === 'number' ? raw.pausedUntil : undefined,
+                        pauseReason: typeof raw.pauseReason === 'string' ? raw.pauseReason : undefined,
+                    };
+                }
+            }
+            catch {
+                // Corrupt ledger: start fresh rather than blocking forever. The next
+                // write re-establishes it; worst case one over-budget launch.
+            }
+        }
+        ledger.launches = ledger.launches.filter((l) => now - l.at < DAY_MS);
+        // Drop reservations whose process died (tolerating PID reuse via the
+        // staleness cutoff) or that outlived any plausible worker run.
+        ledger.active = ledger.active.filter((a) => now - a.at < ACTIVE_STALE_MS && isProcessAlive(a.pid));
+        if (ledger.pausedUntil && ledger.pausedUntil <= now) {
+            ledger.pausedUntil = undefined;
+            ledger.pauseReason = undefined;
+        }
+        return ledger;
+    }
+    writeLedger(ledger) {
+        this.ensureDir();
+        assertNotSymlink(this.ledgerFile);
+        const tmp = `${this.ledgerFile}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(ledger), { mode: 0o600 });
+        fs.renameSync(tmp, this.ledgerFile);
+    }
+    /**
+     * Invariant 10: every launch, denial, and pause emits a receipt. Only
+     * operational metadata is persisted — never prompts or source content.
+     */
+    appendReceipt(receipt) {
+        try {
+            this.ensureDir();
+            assertNotSymlink(this.receiptsFile);
+            fs.appendFileSync(this.receiptsFile, JSON.stringify(receipt) + '\n', { mode: 0o600 });
+            const st = fs.statSync(this.receiptsFile);
+            if (st.size > RECEIPTS_MAX_BYTES) {
+                const lines = fs.readFileSync(this.receiptsFile, 'utf-8').split('\n');
+                fs.writeFileSync(this.receiptsFile, lines.slice(-RECEIPTS_KEEP_LINES).join('\n'), { mode: 0o600 });
+            }
+        }
+        catch {
+            // Receipts are best-effort; never block a decision on them.
+        }
+    }
+}
+// Singleton — one budget per process, shared by all executors.
+let budgetInstance = null;
+export function getGlobalAiBudget() {
+    if (!budgetInstance) {
+        budgetInstance = new GlobalAiBudget();
+    }
+    return budgetInstance;
+}
+/** Test hook: reset the singleton (e.g. after changing RUFLO_AI_BUDGET_DIR). */
+export function resetGlobalAiBudgetForTests() {
+    budgetInstance = null;
+}
+//# sourceMappingURL=global-ai-budget.js.map

package/dist/src/services/headless-worker-executor.d.ts

@@ -131,6 +131,13 @@ export interface HeadlessExecutionResult {
     error?: string;
     /** Execution ID for tracking */
     executionId: string;
+    /**
+     * #2661 — true when the launch was skipped because the same job
+     * (repositoryId + HEAD + worker + config) succeeded within the freshness
+     * window, e.g. in a sibling worktree. No model call happened; consumers
+     * must not overwrite persisted metrics with this result.
+     */
+    dedupSkipped?: boolean;
 }
 /**
  * Pool status information
@@ -246,6 +253,13 @@ export declare class HeadlessWorkerExecutor extends EventEmitter {
      * Get number of active executions
      */
     getActiveCount(): number;
+    /**
+     * #2661 — signal a pool entry's whole process group, not just the head.
+     * Children are spawned `detached: true` on POSIX precisely so their MCP
+     * bridge grandchildren can be reaped with `kill(-pid)`; a head-only kill
+     * orphans them (#2098B).
+     */
+    private killEntryTree;
     /**
      * Cancel a running execution
      */

package/dist/src/services/headless-worker-executor.js

@@ -22,6 +22,9 @@ import { spawn, execSync } from 'child_process';
 import { EventEmitter } from 'events';
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { getGlobalAiBudget, isQuotaErrorText } from './global-ai-budget.js';
+import { resolveGitWorkspaceIdentity } from './git-workspace-identity.js';
+import { getAiJobDedupRegistry, computeAiJobKey, hashWorkerConfig } from './ai-job-dedup.js';
 // ============================================
 // Constants
 // ============================================
@@ -517,6 +520,25 @@ export class HeadlessWorkerExecutor extends EventEmitter {
     getActiveCount() {
         return this.processPool.size;
     }
+    /**
+     * #2661 — signal a pool entry's whole process group, not just the head.
+     * Children are spawned `detached: true` on POSIX precisely so their MCP
+     * bridge grandchildren can be reaped with `kill(-pid)`; a head-only kill
+     * orphans them (#2098B).
+     */
+    killEntryTree(proc, signal) {
+        if (process.platform !== 'win32' && typeof proc.pid === 'number') {
+            try {
+                process.kill(-proc.pid, signal);
+                return;
+            }
+            catch { /* fall through */ }
+        }
+        try {
+            proc.kill(signal);
+        }
+        catch { /* already dead */ }
+    }
     /**
      * Cancel a running execution
      */
@@ -526,7 +548,7 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             return false;
         }
         clearTimeout(entry.timeout);
-        entry.process.kill('SIGTERM');
+        this.killEntryTree(entry.process, 'SIGTERM');
         this.processPool.delete(executionId);
         this.emit('cancelled', { executionId });
         // Process next in queue
@@ -542,12 +564,12 @@ export class HeadlessWorkerExecutor extends EventEmitter {
         const entries = Array.from(this.processPool.entries());
         for (const [executionId, entry] of entries) {
             clearTimeout(entry.timeout);
-            entry.process.kill('SIGTERM');
+            this.killEntryTree(entry.process, 'SIGTERM');
             // SIGKILL fallback after 5s to prevent orphan processes (#1395 Bug 6)
             setTimeout(() => {
                 try {
                     if (!entry.process.killed)
-                        entry.process.kill('SIGKILL');
+                        this.killEntryTree(entry.process, 'SIGKILL');
                 }
                 catch { /* already dead */ }
             }, 5000).unref();
@@ -612,6 +634,63 @@ export class HeadlessWorkerExecutor extends EventEmitter {
         const headless = { ...baseConfig.headless, ...configOverrides };
         const startTime = Date.now();
         const executionId = `${workerType}_${startTime}_${Math.random().toString(36).slice(2, 8)}`;
+        // #2661 invariant 5 — cross-worktree job dedup. Worktrees of one
+        // repository at the same HEAD would otherwise run identical analyses
+        // once per worktree. jobKey = sha256(repositoryId, HEAD, worker,
+        // configHash); a success within the freshness window (the worker's own
+        // interval, floor 10 min) skips the launch entirely — no budget spend,
+        // no process. HEAD moves → new key → the job runs again.
+        const identity = resolveGitWorkspaceIdentity(this.projectRoot);
+        const jobKey = computeAiJobKey({
+            repositoryId: identity.repositoryId,
+            head: identity.head,
+            workerType,
+            configHash: hashWorkerConfig(headless),
+        });
+        const dedup = getAiJobDedupRegistry();
+        const envWindowSecs = Number.parseInt(process.env.RUFLO_AI_DEDUP_WINDOW_SECS || '', 10);
+        const freshnessMs = Number.isFinite(envWindowSecs) && envWindowSecs >= 0
+            ? envWindowSecs * 1000
+            : Math.max(baseConfig.intervalMs || 0, 10 * 60 * 1000);
+        const freshness = dedup.isFresh(jobKey, freshnessMs);
+        if (freshness.fresh) {
+            const skipped = {
+                success: true,
+                dedupSkipped: true,
+                output: '',
+                parsedOutput: undefined,
+                durationMs: 0,
+                model: 'none',
+                sandboxMode: headless.sandbox,
+                workerType,
+                timestamp: new Date(),
+                executionId,
+            };
+            this.logExecution(executionId, 'result', `dedup-skip: job ${jobKey.slice(0, 12)} succeeded ${Math.round((Date.now() - (freshness.lastRunAt ?? Date.now())) / 1000)}s ago (repo ${identity.repositoryId.slice(0, 12)}, head ${identity.head.slice(0, 12) || 'n/a'})`);
+            this.emit('dedup:skipped', { executionId, workerType, jobKey, lastRunAt: freshness.lastRunAt });
+            this.processQueue();
+            return skipped;
+        }
+        // #2661 — every autonomous launch must reserve a slot in the USER-GLOBAL
+        // AI budget before any process is created. This is the hard invariant
+        // that bounds aggregate launches across all worktree daemons: per-daemon
+        // maxConcurrent limits multiply with worktree count, the global budget
+        // does not. Denials return an error result (with a receipted reason)
+        // instead of queueing, so denied work never piles up into a retry storm.
+        const budget = getGlobalAiBudget();
+        const model = headless.model || 'sonnet';
+        const permit = await budget.reserve({ workerType, model, workspace: this.projectRoot });
+        if (!permit.allowed) {
+            const denied = this.createErrorResult(workerType, `Denied by global AI budget: ${permit.reason}`);
+            denied.executionId = executionId;
+            this.logExecution(executionId, 'error', `budget-denied: ${permit.reason}`);
+            // NOTE: deliberately no `emit('error', ...)` here — Node treats
+            // unlistened 'error' events as throws, and callers consume the
+            // returned error result; `budget:denied` is the observable signal.
+            this.emit('budget:denied', { executionId, workerType, reason: permit.reason });
+            this.processQueue();
+            return denied;
+        }
         this.emit('start', { executionId, workerType, config: headless });
         try {
             // Build context from file patterns
@@ -651,6 +730,23 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             };
             // Log result
             this.logExecution(executionId, 'result', JSON.stringify(executionResult, null, 2));
+            // #2661 invariant 5 — record the success so sibling worktrees at the
+            // same HEAD skip this job for the rest of the freshness window.
+            if (result.success) {
+                dedup.recordSuccess(jobKey, {
+                    workerType,
+                    repositoryId: identity.repositoryId,
+                    workspace: this.projectRoot,
+                });
+            }
+            // #2661 — a quota/429/usage-limit failure opens the user-global
+            // circuit breaker so EVERY daemon stops launching for the cooldown
+            // window instead of retrying into an exhausted quota. Only inspected
+            // on failure: successful analysis output may legitimately discuss
+            // rate limiting in the user's own code.
+            if (!result.success && isQuotaErrorText(result.error)) {
+                await budget.recordQuotaError(`${workerType}: ${(result.error ?? '').slice(0, 200)}`);
+            }
             this.emit('complete', executionResult);
             return executionResult;
         }
@@ -660,10 +756,15 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             executionResult.executionId = executionId;
             executionResult.durationMs = Date.now() - startTime;
             this.logExecution(executionId, 'error', errorMessage);
+            if (isQuotaErrorText(errorMessage)) {
+                await budget.recordQuotaError(`${workerType}: ${errorMessage.slice(0, 200)}`);
+            }
             this.emit('error', executionResult);
             return executionResult;
         }
         finally {
+            // #2661 — free the global concurrency slot (launch counts persist).
+            await budget.release(permit.permitId);
             // Process next in queue
             this.processQueue();
         }

package/dist/src/services/worker-daemon.d.ts

@@ -58,6 +58,7 @@ export interface DaemonConfig {
     };
     ttlMs: number;
     idleShutdownMs: number;
+    aiWorkersEnabled: boolean;
     workers: WorkerConfig[];
 }
 /**
@@ -237,6 +238,19 @@ export declare class WorkerDaemon extends EventEmitter {
      * on its own. A no-op when both limits are disabled (0).
      */
     private startLifecycleMonitor;
+    /**
+     * Decide whether the daemon should self-shutdown, and why. Extracted from
+     * the lifecycle timer so it is testable without racing a 60s interval or
+     * calling process.exit().
+     *
+     * #2661 (invariant 6, containment form): a removed worktree makes its
+     * daemon ineligible within one check interval — the daemon detects that
+     * its workspace directory is gone and shuts down instead of continuing to
+     * schedule jobs against a deleted tree. The full lease architecture
+     * (supervisor-dispatched jobs, heartbeats) is follow-up work; this stops
+     * the leak where recreated/removed worktrees leave schedulers behind.
+     */
+    private lifecycleShutdownReason;
     /**
      * Most recent worker start/finish time across all workers (epoch ms), or
      * null if no worker has ever started. Used for idle-shutdown detection.