@claude-flow/cli 3.26.1 → 3.27.0

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

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.26.1",
+    "version": "3.27.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "2a18a761f0dc4839df8b6eeadf8f0ceb6badcc5bf14414c91555711a5e9d4bdc",
@@ -8,6 +8,6 @@
       "statusline.cjs": "8abc67b7512e66fe5f8fe6cc5f099f827de6f7e2023a493f920090248d326e01"
     }
   },
-  "signature": "WJv7lzA3G5RhBcD8z7v1+uGwPHY6aIEoIPgOW5QjH3fRHvL0vMC7tVR+1QviVQtQY0hblBYrK4bpvFqzoFukAw==",
+  "signature": "f0oa4b6TIdjXxPc8TFjFEXODgr4+gNsdQXc54NszbvhpR066pXyaCgxrYTsN9iRwFFY1dp6RtaUCuaMpN4NqDg==",
   "algorithm": "ed25519"
 }

package/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/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/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/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

package/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/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/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