claude-flow 3.26.0 → 3.27.0

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

@@ -0,0 +1,136 @@
+/**
+ * #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.
+ */
+import * as fs from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function computeAiJobKey(parts) {
+    return createHash('sha256')
+        .update([parts.repositoryId, parts.head, parts.workerType, parts.configHash].join('\n'))
+        .digest('hex');
+}
+/** Stable hash of an arbitrary config object (key-sorted JSON). */
+export function hashWorkerConfig(config) {
+    const canonical = JSON.stringify(config, (_k, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return v;
+    });
+    return createHash('sha256').update(canonical ?? 'null').digest('hex');
+}
+/** Invariant 9: registry files must never be symlinks. */
+function assertNotSymlink(path) {
+    try {
+        const st = fs.lstatSync(path);
+        if (st.isSymbolicLink()) {
+            throw new Error(`AI job registry is a symlink (refusing): ${path}`);
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+}
+export class AiJobDedupRegistry {
+    dir;
+    file;
+    constructor(options) {
+        this.dir = options?.baseDir
+            ?? process.env.RUFLO_AI_BUDGET_DIR
+            ?? join(homedir(), '.claude-flow');
+        this.file = join(this.dir, 'ai-jobs.json');
+    }
+    /**
+     * 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, freshnessMs) {
+        if (process.env.RUFLO_AI_DEDUP_DISABLE === '1')
+            return { fresh: false };
+        try {
+            const records = this.read();
+            const rec = records[jobKey];
+            if (rec && Date.now() - rec.at < freshnessMs) {
+                return { fresh: true, lastRunAt: rec.at };
+            }
+            return { fresh: false, lastRunAt: rec?.at };
+        }
+        catch {
+            return { fresh: false };
+        }
+    }
+    /** Record a successful run of a job. Best-effort. */
+    recordSuccess(jobKey, meta) {
+        try {
+            const records = this.read();
+            records[jobKey] = { at: Date.now(), ...meta };
+            this.write(records);
+        }
+        catch { /* dedup is an optimization — never block on it */ }
+    }
+    read() {
+        assertNotSymlink(this.file);
+        if (!fs.existsSync(this.file))
+            return {};
+        const raw = JSON.parse(fs.readFileSync(this.file, 'utf-8'));
+        if (!raw || typeof raw !== 'object')
+            return {};
+        // Prune anything older than 24h — freshness windows are far shorter,
+        // and HEAD churn would otherwise grow the file without bound.
+        const now = Date.now();
+        const out = {};
+        for (const [key, rec] of Object.entries(raw)) {
+            if (rec && typeof rec.at === 'number' && now - rec.at < DAY_MS) {
+                out[key] = rec;
+            }
+        }
+        return out;
+    }
+    write(records) {
+        if (!fs.existsSync(this.dir)) {
+            fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        }
+        assertNotSymlink(this.file);
+        const tmp = `${this.file}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(records), { mode: 0o600 });
+        fs.renameSync(tmp, this.file);
+    }
+}
+// Singleton — one registry per process.
+let registryInstance = null;
+export function getAiJobDedupRegistry() {
+    if (!registryInstance) {
+        registryInstance = new AiJobDedupRegistry();
+    }
+    return registryInstance;
+}
+/** Test hook: reset the singleton (e.g. after changing RUFLO_AI_BUDGET_DIR). */
+export function resetAiJobDedupRegistryForTests() {
+    registryInstance = null;
+}
+//# sourceMappingURL=ai-job-dedup.js.map

package/v3/@claude-flow/cli/dist/src/services/git-workspace-identity.d.ts

@@ -0,0 +1,42 @@
+/**
+ * #2661 — Git workspace identity: separate WORKTREE identity from
+ * REPOSITORY identity.
+ *
+ * Daemon dedup, state, and scheduling have historically been keyed on the
+ * worktree path (`process.cwd()`), so N Git worktrees of the same repository
+ * behave as N unrelated projects — the cardinality bug behind the worktree
+ * daemon fanout. This service resolves the identity that is SHARED across
+ * worktrees:
+ *
+ *   worktreeRoot   `git rev-parse --show-toplevel`   — per-worktree
+ *   commonGitDir   `git rev-parse --git-common-dir`  — shared by all worktrees
+ *   repositoryId   sha256(canonical commonGitDir)    — stable repo key
+ *   head           `git rev-parse HEAD`              — current commit
+ *
+ * Two worktrees of one repository resolve to the SAME repositoryId (and,
+ * when checked out at the same commit, the same head) — the key ingredient
+ * for cross-worktree job dedup (issue invariant 5).
+ *
+ * Non-git directories degrade gracefully: repositoryId falls back to a hash
+ * of the resolved directory path (prefixed `dir:`-style via isGit=false), so
+ * callers never need a special case.
+ */
+export interface GitWorkspaceIdentity {
+    /** Absolute root of this worktree (or the input dir when not a git repo). */
+    worktreeRoot: string;
+    /** Absolute path of the shared .git directory (equals worktreeRoot/.git for non-worktree clones). */
+    commonGitDir: string;
+    /** Stable id shared by ALL worktrees of one repository. */
+    repositoryId: string;
+    /** Current HEAD commit sha ('' when not a git repo or unborn HEAD). */
+    head: string;
+    /** False when the directory is not inside a git repository. */
+    isGit: boolean;
+}
+/**
+ * Resolve the git workspace identity for a directory. Never throws.
+ */
+export declare function resolveGitWorkspaceIdentity(dir: string): GitWorkspaceIdentity;
+/** Test hook: clear the per-process identity cache. */
+export declare function resetGitIdentityCacheForTests(): void;
+//# sourceMappingURL=git-workspace-identity.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/git-workspace-identity.js

@@ -0,0 +1,99 @@
+/**
+ * #2661 — Git workspace identity: separate WORKTREE identity from
+ * REPOSITORY identity.
+ *
+ * Daemon dedup, state, and scheduling have historically been keyed on the
+ * worktree path (`process.cwd()`), so N Git worktrees of the same repository
+ * behave as N unrelated projects — the cardinality bug behind the worktree
+ * daemon fanout. This service resolves the identity that is SHARED across
+ * worktrees:
+ *
+ *   worktreeRoot   `git rev-parse --show-toplevel`   — per-worktree
+ *   commonGitDir   `git rev-parse --git-common-dir`  — shared by all worktrees
+ *   repositoryId   sha256(canonical commonGitDir)    — stable repo key
+ *   head           `git rev-parse HEAD`              — current commit
+ *
+ * Two worktrees of one repository resolve to the SAME repositoryId (and,
+ * when checked out at the same commit, the same head) — the key ingredient
+ * for cross-worktree job dedup (issue invariant 5).
+ *
+ * Non-git directories degrade gracefully: repositoryId falls back to a hash
+ * of the resolved directory path (prefixed `dir:`-style via isGit=false), so
+ * callers never need a special case.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import { resolve } from 'path';
+import * as fs from 'fs';
+const GIT_TIMEOUT_MS = 3000;
+function git(cwd, ...args) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+// Identity is stable for the life of a process (repo location doesn't move),
+// but HEAD is not — cache only the expensive, stable parts per directory.
+const identityCache = new Map();
+/**
+ * Resolve the git workspace identity for a directory. Never throws.
+ */
+export function resolveGitWorkspaceIdentity(dir) {
+    const resolved = resolve(dir);
+    let stable = identityCache.get(resolved);
+    if (!stable) {
+        const worktreeRoot = git(resolved, 'rev-parse', '--show-toplevel');
+        if (!worktreeRoot) {
+            stable = {
+                worktreeRoot: resolved,
+                commonGitDir: '',
+                // 'dir:' prefix keeps non-git ids from ever colliding with repo ids.
+                repositoryId: sha256(`dir:${canonicalPath(resolved)}`),
+                isGit: false,
+            };
+        }
+        else {
+            // --git-common-dir may be relative to the worktree root (git < 2.31
+            // and some invocation contexts) — resolve against it.
+            const rawCommon = git(worktreeRoot, 'rev-parse', '--git-common-dir') ?? '.git';
+            const commonGitDir = resolve(worktreeRoot, rawCommon);
+            stable = {
+                worktreeRoot,
+                commonGitDir,
+                repositoryId: sha256(`git:${canonicalPath(commonGitDir)}`),
+                isGit: true,
+            };
+        }
+        identityCache.set(resolved, stable);
+    }
+    const head = stable.isGit ? (git(stable.worktreeRoot, 'rev-parse', 'HEAD') ?? '') : '';
+    return { ...stable, head };
+}
+/**
+ * Canonicalize a path so the same repository yields the same repositoryId
+ * regardless of symlinked prefixes (/tmp vs /private/tmp on macOS, etc.).
+ */
+function canonicalPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Test hook: clear the per-process identity cache. */
+export function resetGitIdentityCacheForTests() {
+    identityCache.clear();
+}
+//# sourceMappingURL=git-workspace-identity.js.map

package/v3/@claude-flow/cli/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