@claude-flow/cli 3.27.3 → 3.28.0

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

@@ -1,13 +1,13 @@
 {
   "manifest": {
-    "version": "3.27.3",
+    "version": "3.28.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "2e4927ff158c0079a67a6f0ef0b99ac748d600d33798b0a5fbd5a6a82225ec03",
       "intelligence.cjs": "bd1f8e4b034944aee1df0391dc47ac2e8cc4b3aa542c65407a59d49620bbf76b",
-      "statusline.cjs": "ca46b9c780fee974d4b54cfd610b3b09d77c78c40761dc49ae76355da2f643ba"
+      "statusline.cjs": "8ce3ea9b732baaad8dd0df4123760496ad2f857b6c3ab2b55b4de879b5cf7276"
     }
   },
-  "signature": "XuS7Mn0CwcqZYTTEoSRuCXG3f9fH7Mu7pILRJi86I+Qj4tDmaroqEhu8TWN1PEVXCK5tiLTMnG20ZxcY+twbDg==",
+  "signature": "K7iXHhAaLffQjHpnBB3K9PtOwYreUOw9aROTN5jkb+bn7BH4dzdaDT/L0nBJstvt8uzUZHhAZSXRjnXR5malDw==",
   "algorithm": "ed25519"
 }

package/.claude/helpers/statusline.cjs

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

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 1,
-  "generatedAt": "2026-07-14T04:26:59.494Z",
-  "gitSha": "6643d44d",
+  "generatedAt": "2026-07-14T05:33:57.949Z",
+  "gitSha": "f2208820",
   "catalog": {
     "agents": 164,
     "tools": 387,

package/dist/src/commands/daemon.d.ts

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

package/dist/src/commands/daemon.js

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

package/dist/src/commands/init.js

@@ -468,7 +468,9 @@ const initAction = async (ctx) => {
             output.writeln(output.bold('Next steps:'));
             output.printList([
                 `Run ${output.highlight(`${bin} daemon start`)} to start background workers`,
-                `Run ${output.highlight(`${bin} memory init`)} to initialize memory database`,
+                // Memory is initialized automatically during init (persistent by
+                // default — see executor.ts) — no separate `memory init` step needed
+                // unless the DB was skipped (MINIMAL_INIT_OPTIONS) or needs --force.
                 `Run ${output.highlight(`${bin} swarm init`)} to initialize a swarm`,
                 `Or use ${output.highlight(`${bin} init --start-all`)} to do all of the above`,
                 options.components.settings ? `Review ${output.highlight('.claude/settings.json')} for hook configurations` : '',

package/dist/src/init/executor.js

@@ -212,15 +212,39 @@ export async function executeInit(options) {
             // the `vector_indexes` table (older CLI / agentdb-written), self-heal it
             // so the statusline vector count + namespace routing work. Best-effort,
             // dynamically imported so a WASM-only host without better-sqlite3 just
-            // skips it. Fresh projects have no DB yet — this is a no-op there.
+            // skips it.
+            //
+            // Persistent memory ON BY DEFAULT: `runtime.memoryBackend` already
+            // defaults to 'hybrid' in DEFAULT_INIT_OPTIONS, but that only ever
+            // configured the DECLARED backend — the actual .swarm/memory.db file
+            // was never created until something eventually called `memory store`
+            // or the user ran `memory init --force` by hand (both the generated
+            // CLAUDE.md and the quickstart docs told users to do this as a
+            // separate step). A fresh project could sit for days looking
+            // "configured for AgentDB" while genuinely capturing nothing, with no
+            // signal that the config and the on-disk reality had diverged. Fresh
+            // projects now get the DB eagerly created here, matching what
+            // `memoryBackend` already promised; MINIMAL_INIT_OPTIONS
+            // (memoryBackend: 'memory') opts out, matching its non-persistent intent.
             try {
                 const memDbPath = path.join(targetDir, '.swarm', 'memory.db');
                 if (fs.existsSync(memDbPath)) {
                     const { repairVectorIndexes } = await import('../memory/memory-initializer.js');
                     await repairVectorIndexes(memDbPath, { autoRecover: true });
                 }
+                else if (options.runtime.memoryBackend !== 'memory') {
+                    const { initializeMemoryDatabase } = await import('../memory/memory-initializer.js');
+                    const initResult = await initializeMemoryDatabase({
+                        backend: options.runtime.memoryBackend,
+                        dbPath: memDbPath,
+                        verbose: false,
+                    });
+                    if (initResult.success) {
+                        result.created.files.push('.swarm/memory.db');
+                    }
+                }
             }
-            catch { /* best-effort — never block init on memory repair */ }
+            catch { /* best-effort — never block init on memory setup */ }
         }
         // Generate statusline
         if (options.components.statusline) {

package/dist/src/init/statusline-generator.js

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

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

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

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

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

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

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

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

@@ -336,6 +336,42 @@ export function isLocalWorker(type) {
 export function getModelId(model) {
     return MODEL_IDS[model];
 }
+/**
+ * #2661 root-fix — best-effort parse of `claude --print --output-format
+ * json`'s response envelope. Deliberately lenient: probes a couple of
+ * plausible field-name shapes (the CLI's JSON schema is not a versioned
+ * public contract) and returns null on anything unexpected rather than
+ * throwing, so a schema mismatch degrades to "no usage captured" — the
+ * caller then falls back to the raw stdout text, exactly today's behavior.
+ * Exported for direct unit testing without spawning a real process.
+ */
+export function parseClaudePrintJsonEnvelope(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed[0] !== '{')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const result = typeof obj.result === 'string' ? obj.result : undefined;
+    if (result === undefined)
+        return null; // not the envelope shape we expect
+    const usage = (obj.usage && typeof obj.usage === 'object') ? obj.usage : undefined;
+    const numOrUndef = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+    return {
+        result,
+        inputTokens: numOrUndef(usage?.input_tokens ?? usage?.inputTokens),
+        outputTokens: numOrUndef(usage?.output_tokens ?? usage?.outputTokens),
+        costUsd: numOrUndef(obj.total_cost_usd ?? obj.cost_usd ?? obj.totalCostUsd),
+        durationMs: numOrUndef(obj.duration_ms ?? obj.durationMs),
+    };
+}
 /**
  * Get worker configuration by type
  */
@@ -721,6 +757,9 @@ export class HeadlessWorkerExecutor extends EventEmitter {
                 parsedOutput,
                 durationMs: Date.now() - startTime,
                 tokensUsed: result.tokensUsed,
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                costUsd: result.costUsd,
                 model: headless.model || 'sonnet',
                 sandboxMode: headless.sandbox,
                 workerType,
@@ -730,6 +769,17 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             };
             // Log result
             this.logExecution(executionId, 'result', JSON.stringify(executionResult, null, 2));
+            // #2661 root-fix — structured per-launch telemetry, receipted
+            // regardless of success/failure (a failed launch still spent
+            // whatever tokens it spent before erroring).
+            budget.recordUsage(permit.permitId, {
+                workerType,
+                model,
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                durationMs: result.apiDurationMs ?? executionResult.durationMs,
+                costUsd: result.costUsd,
+            });
             // #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) {
@@ -988,7 +1038,15 @@ Analyze the above codebase context and provide your response following the forma
             // diagnosed as a 5-second redispatch + subprocess-table growth.
             // `detached: true` puts the child in its own process group so we
             // can signal the whole tree with `process.kill(-pid, sig)`.
-            const child = spawn('claude', ['--print'], {
+            // #2661 root-fix — structured usage telemetry. `--output-format json`
+            // wraps the response in an envelope carrying `result` (the actual
+            // text — what `output` must still contain, unchanged for every
+            // existing downstream parser) alongside `usage`/cost/duration
+            // metadata. Parsing is lenient (parseClaudePrintJsonEnvelope below)
+            // and ALWAYS falls back to the raw text on any mismatch — a schema
+            // surprise from an older/newer `claude` CLI must degrade to exactly
+            // today's behavior (no usage captured), never break analysis output.
+            const child = spawn('claude', ['--print', '--output-format', 'json'], {
                 cwd: this.projectRoot,
                 env,
                 stdio: ['pipe', 'pipe', 'pipe'],
@@ -1068,9 +1126,17 @@ Analyze the above codebase context and provide your response following the forma
                     return;
                 resolved = true;
                 cleanup();
+                const envelope = parseClaudePrintJsonEnvelope(stdout);
                 resolve({
                     success: code === 0,
-                    output: stdout || stderr,
+                    output: envelope?.result ?? stdout ?? stderr,
+                    inputTokens: envelope?.inputTokens,
+                    outputTokens: envelope?.outputTokens,
+                    tokensUsed: envelope
+                        ? (envelope.inputTokens ?? 0) + (envelope.outputTokens ?? 0)
+                        : undefined,
+                    costUsd: envelope?.costUsd,
+                    apiDurationMs: envelope?.durationMs,
                     error: code !== 0 ? stderr || `Process exited with code ${code}` : undefined,
                 });
             });