@claude-flow/cli 3.63.9 → 3.65.0

package/dist/src/commands/init.js

@@ -11,6 +11,39 @@ import { executeInit, executeUpgrade, executeUpgradeWithMissing, DEFAULT_INIT_OP
 import { executeGrokInit } from '../init/grok-generator.js';
 import { ENROLLMENT_SCREEN, recordEnrollmentOutcome, shouldOfferEnrollment, } from '../funnel/enrollment.js';
 import { commandExists } from '../services/harness-hosts.js';
+import { riskyModeFromFlags } from '../init/risky-settings-gate.js';
+const RISKY_FLAG_OPTIONS = [
+    {
+        // ADR-509 §2.3
+        name: 'keep-risky-settings',
+        description: 'Carry forward project auto-approve keys found in .claude/settings.json (enableAllProjectMcpServers, enabledMcpjsonServers, bypassPermissions, blanket Bash allows, non-ruflo hooks) instead of stopping',
+        type: 'boolean',
+        default: false,
+    },
+    {
+        name: 'drop-risky-settings',
+        description: 'Write the merged .claude/settings.json without those auto-approve keys instead of stopping',
+        type: 'boolean',
+        default: false,
+    },
+];
+/** ADR-509 §2.3 — print the keys init stopped on (or kept/dropped). Returns the exit result when it stopped. */
+function reportRiskySettings(result, mode) {
+    if (!result.riskySettings?.length)
+        return null;
+    const head = result.stoppedOnRiskySettings
+        ? 'Stopped: .claude/settings.json carries project auto-approve keys that would be carried forward:'
+        : mode === 'drop'
+            ? 'Dropped these project auto-approve keys from .claude/settings.json:'
+            : 'Kept these project auto-approve keys in .claude/settings.json (--keep-risky-settings):';
+    (result.stoppedOnRiskySettings ? output.printError : output.printWarning).call(output, head);
+    for (const line of result.riskySettings)
+        output.printInfo(`  • ${line}`);
+    if (!result.stoppedOnRiskySettings)
+        return null;
+    output.printInfo('Nothing was written. Re-run with --drop-risky-settings to write the merged settings without these keys, or --keep-risky-settings to keep them.');
+    return { success: false, exitCode: 1, message: 'Stopped on risky project settings', data: { riskySettings: result.riskySettings } };
+}
 /**
  * ADR-302 post-init capability enrollment. One-time, interactive-TTY-only,
  * skippable with --no-signup, auto-skipped in CI/automation. Never throws
@@ -694,12 +727,22 @@ const initClaudeAction = async (ctx) => {
     if (noGlobal) {
         options.skipGlobalClaudeMd = true;
     }
+    const riskyMode = riskyModeFromFlags(ctx.flags);
+    if (typeof riskyMode === 'object') {
+        output.printError(riskyMode.error);
+        return { success: false, exitCode: 1 };
+    }
+    options.riskySettings = riskyMode;
     // Create spinner
     const spinner = output.createSpinner({ text: 'Initializing...' });
     spinner.start();
     try {
         // Execute initialization
         const result = await executeInit(options);
+        if (result.stoppedOnRiskySettings) {
+            spinner.fail('Initialization stopped');
+            return reportRiskySettings(result, riskyMode);
+        }
         if (!result.success) {
             spinner.fail('Initialization failed');
             for (const error of result.errors) {
@@ -708,6 +751,7 @@ const initClaudeAction = async (ctx) => {
             return { success: false, exitCode: 1 };
         }
         spinner.succeed('RuFlo V3 initialized successfully!');
+        reportRiskySettings(result, riskyMode);
         output.writeln();
         // Display summary
         const summary = [];
@@ -1157,7 +1201,13 @@ const wizardCommand = {
             output.writeln();
             const spinner = output.createSpinner({ text: 'Initializing...' });
             spinner.start();
+            const wizardRisky = riskyModeFromFlags(ctx.flags);
+            options.riskySettings = typeof wizardRisky === 'object' ? 'stop' : wizardRisky;
             const result = await executeInit(options);
+            if (result.stoppedOnRiskySettings) {
+                spinner.fail('Setup stopped');
+                return reportRiskySettings(result, options.riskySettings);
+            }
             if (!result.success) {
                 spinner.fail('Initialization failed');
                 for (const error of result.errors) {
@@ -1362,6 +1412,7 @@ const hooksCommand = {
     description: 'Initialize only hooks configuration',
     options: [
         { name: 'all', description: 'Enable all hooks', type: 'boolean', default: true },
+        ...RISKY_FLAG_OPTIONS,
         { name: 'minimal', description: 'Enable only essential hooks', type: 'boolean', default: false },
     ],
     action: async (ctx) => {
@@ -1403,9 +1454,19 @@ const hooksCommand = {
                 }
                 : DEFAULT_INIT_OPTIONS.hooks,
         };
+        const hooksRisky = riskyModeFromFlags(ctx.flags);
+        if (typeof hooksRisky === 'object') {
+            output.printError(hooksRisky.error);
+            return { success: false, exitCode: 1 };
+        }
+        options.riskySettings = hooksRisky;
         const spinner = output.createSpinner({ text: 'Creating hooks configuration...' });
         spinner.start();
         const result = await executeInit(options);
+        if (result.stoppedOnRiskySettings) {
+            spinner.fail('Hooks configuration stopped');
+            return reportRiskySettings(result, hooksRisky);
+        }
         if (result.success) {
             spinner.succeed(`Created settings.json with ${result.summary.hooksEnabled} hooks enabled`);
             if (result.warnings && result.warnings.length > 0) {
@@ -1465,8 +1526,14 @@ const upgradeCommand = {
             type: 'boolean',
             default: true,
         },
+        ...RISKY_FLAG_OPTIONS,
     ],
     action: async (ctx) => {
+        const upgradeRisky = riskyModeFromFlags(ctx.flags);
+        if (typeof upgradeRisky === 'object') {
+            output.printError(upgradeRisky.error);
+            return { success: false, exitCode: 1 };
+        }
         const addMissing = (ctx.flags['add-missing'] || ctx.flags.addMissing);
         const upgradeSettings = (ctx.flags.settings);
         const upgradeMods = ctx.flags.mods === true || (ctx.flags.mods !== false && (addMissing || upgradeSettings));
@@ -1492,8 +1559,13 @@ const upgradeCommand = {
         spinner.start();
         try {
             const result = addMissing
-                ? await executeUpgradeWithMissing(ctx.cwd, upgradeSettings)
-                : await executeUpgrade(ctx.cwd, upgradeSettings);
+                ? await executeUpgradeWithMissing(ctx.cwd, upgradeSettings, upgradeRisky)
+                : await executeUpgrade(ctx.cwd, upgradeSettings, upgradeRisky);
+            if (result.stoppedOnRiskySettings) {
+                spinner.fail('Upgrade stopped');
+                return reportRiskySettings(result, upgradeRisky);
+            }
+            reportRiskySettings(result, upgradeRisky);
             if (!result.success) {
                 spinner.fail('Upgrade failed');
                 for (const error of result.errors) {
@@ -1594,6 +1666,7 @@ export const initCommand = {
     description: 'Initialize RuFlo in the current directory',
     subcommands: [wizardCommand, checkCommand, skillsCommand, hooksCommand, upgradeCommand],
     options: [
+        ...RISKY_FLAG_OPTIONS,
         {
             name: 'force',
             short: 'f',
@@ -1748,6 +1821,7 @@ export const initCommand = {
         { command: 'claude-flow init --minimal', description: 'Initialize with minimal configuration' },
         { command: 'claude-flow init --full', description: 'Initialize with all components' },
         { command: 'claude-flow init --force', description: 'Reinitialize and overwrite existing config' },
+        { command: 'claude-flow init --drop-risky-settings', description: 'Merge into an existing settings.json without its auto-approve keys (init stops on them otherwise)' },
         { command: 'claude-flow init --only-claude', description: 'Only create Claude Code integration' },
         { command: 'claude-flow init --skip-claude', description: 'Only create V3 runtime' },
         { command: 'claude-flow init wizard', description: 'Interactive setup wizard' },

package/dist/src/commands/mods.js

@@ -13,6 +13,11 @@ import { join, resolve } from 'node:path';
 import { directoryMarketplace, MARKETPLACE_NAME } from '../mods/install.js';
 import { probeMods } from '../mods/probe.js';
 import { applyMods, removeMods } from '../mods/apply.js';
+import { signatureFindings } from '../mods/install-trust.js';
+import { acceptRiskFrom } from '../plugins/marketplace-trust/scan.js';
+import { claudeConfigDir, marketplaceState } from '../mods/plugin-resolve.js';
+import { MOD_PLUGINS } from '../mods/install.js';
+import { homedir } from 'node:os';
 /**
  * `--source local` / `--marketplace-path <dir>`: a ruflo checkout as a
  * directory marketplace (dogfooding). It must be a ruflo marketplace.
@@ -53,6 +58,7 @@ const installSub = {
         { name: 'strict', description: 'Exit 1 when a required plugin could not be made loadable', type: 'boolean', default: false },
         { name: 'source', description: 'github (ruvnet/ruflo, default) | local (a ruflo checkout as a directory marketplace: plugins load live from it)', type: 'string', default: 'github' },
         { name: 'marketplace-path', description: 'With --source local: the ruflo checkout (default: the project root)', type: 'string' },
+        { name: 'accept-risk', description: 'Install this plugin (name, comma list) even though the pre-install scan found a high-severity issue; recorded in .claude-flow/mods/install.json (ADR-509)', type: 'string' },
     ],
     action: async (ctx) => {
         const scope = ctx.flags.scope ?? 'local';
@@ -80,6 +86,7 @@ const installSub = {
             marketplace,
             dryRun: ctx.flags.dryRun === true || ctx.flags['dry-run'] === true,
             pluginInstall: ctx.flags.pluginInstall !== false && ctx.flags['plugin-install'] !== false,
+            acceptRisk: acceptRiskFrom(ctx.flags),
         });
         if (result.install.dryRun)
             return { success: true, data: result };
@@ -120,6 +127,11 @@ function findingsCommand(name, description) {
         ],
         action: async (ctx) => {
             const findings = probeMods({ projectRoot: projectRoot(ctx) });
+            if (name === 'doctor') {
+                // ADR-509 §2.1: check the clone (and install cache) against the release signatures; writes the status the mod's trust gate reads.
+                const configDir = claudeConfigDir(process.env, homedir());
+                findings.push(...signatureFindings(configDir, marketplaceState(configDir).location, MOD_PLUGINS.map((p) => p.id.split('@')[0])));
+            }
             if (ctx.flags.json)
                 output.printJson(findings);
             else
@@ -175,6 +187,7 @@ export const modsCommand = {
         { command: 'ruflo mods install --no-plugin-install', description: 'Only write settings; run no claude command' },
         { command: 'ruflo mods install --source local', description: 'Dogfood: load the mods live from this ruflo checkout (directory marketplace)' },
         { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy? Each problem prints a one-line fix' },
+        { command: 'ruflo mods install --accept-risk ruflo-console', description: 'Install past a high pre-install scan finding for that one plugin (recorded)' },
         { command: 'ruflo mods doctor --strict', description: 'Same, and exit 1 when anything is not fully working (for CI)' },
         { command: 'ruflo mods uninstall', description: 'Remove only what install added' },
     ],

package/dist/src/commands/plugins-paths.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ADR-510 §2.3 — `ruflo plugins paths [--json] [--names a,b]`.
+ *
+ * Prints the folder each ruflo plugin resolves to (the same resolver headless
+ * workers use for `--plugin-dir`), so an Agent SDK caller can build
+ * `plugins: [{ type: "local", path }]`, and lists plugins that could not be
+ * found. Read-only.
+ */
+import type { Command } from '../types.js';
+/** Default list: every plugin `ruflo mods install` enables. */
+export declare const DEFAULT_PATH_PLUGINS: readonly string[];
+export declare const pathsCommand: Command;
+//# sourceMappingURL=plugins-paths.d.ts.map

package/dist/src/commands/plugins-paths.js

@@ -0,0 +1,55 @@
+/**
+ * ADR-510 §2.3 — `ruflo plugins paths [--json] [--names a,b]`.
+ *
+ * Prints the folder each ruflo plugin resolves to (the same resolver headless
+ * workers use for `--plugin-dir`), so an Agent SDK caller can build
+ * `plugins: [{ type: "local", path }]`, and lists plugins that could not be
+ * found. Read-only.
+ */
+import { output } from '../output.js';
+import { MOD_PLUGIN_IDS } from '../mods/install.js';
+import { resolvePluginPaths } from '../mods/plugin-paths.js';
+/** Default list: every plugin `ruflo mods install` enables. */
+export const DEFAULT_PATH_PLUGINS = MOD_PLUGIN_IDS.map((id) => id.split('@')[0]);
+const PLUGIN_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+export const pathsCommand = {
+    name: 'paths',
+    description: 'Print the local folder of each ruflo plugin (for claude -p --plugin-dir or Agent SDK plugins)',
+    options: [
+        { name: 'names', short: 'n', type: 'string', description: `Comma list of plugin names (default: ${DEFAULT_PATH_PLUGINS.join(',')})` },
+        { name: 'json', type: 'boolean', description: 'Print { resolved, missing } as JSON', default: false },
+    ],
+    examples: [
+        { command: 'ruflo plugins paths', description: 'Where ruflo-mods, ruflo-swarm and ruflo-console live on this machine' },
+        { command: 'ruflo plugins paths --names ruflo-mods --json', description: 'JSON for an Agent SDK plugins array' },
+    ],
+    action: async (ctx) => {
+        const raw = ctx.flags.names;
+        const names = raw ? raw.split(',').map((s) => s.trim()).filter(Boolean) : [...DEFAULT_PATH_PLUGINS];
+        const bad = names.filter((n) => !PLUGIN_NAME.test(n.split('@')[0]));
+        if (bad.length > 0) {
+            const message = `invalid plugin name: ${bad.map((b) => JSON.stringify(b)).join(', ')}`;
+            if (ctx.flags.json)
+                output.writeln(JSON.stringify({ resolved: [], missing: [], error: message }));
+            else
+                output.printError(message);
+            return { success: false, exitCode: 1, message };
+        }
+        const result = resolvePluginPaths(names, { projectRoot: ctx.cwd || process.cwd() });
+        if (ctx.flags.json) {
+            output.writeln(JSON.stringify(result, null, 2));
+        }
+        else {
+            for (const p of result.resolved)
+                output.writeln(`${p.name}\t${p.path}\t(${p.source})`);
+            for (const m of result.missing)
+                output.writeln(output.dim(`${m.name}\tmissing: ${m.reason}`));
+            if (result.resolved.length > 0) {
+                output.writeln(output.dim('Agent SDK: plugins: [{ type: "local", path }] — check the init message\'s plugin_errors'));
+            }
+        }
+        // Missing plugins are reported, not an error: a worker still runs without them.
+        return { success: true, exitCode: 0, data: result };
+    },
+};
+//# sourceMappingURL=plugins-paths.js.map

package/dist/src/commands/plugins-verify.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../types.js';
+export declare const verifyCommand: Command;
+/**
+ * ADR-509 §2.2 for `ruflo plugins install -n <local path>`: a high finding
+ * stops the install unless --accept-risk names the plugin (its directory name).
+ * Returns an error message when the install must stop.
+ */
+export declare function scanLocalPluginBeforeInstall(dir: string, acceptRisk: readonly string[]): string | null;
+//# sourceMappingURL=plugins-verify.d.ts.map

package/dist/src/commands/plugins-verify.js

@@ -0,0 +1,92 @@
+/**
+ * ADR-509 — `ruflo plugins verify [name]` and the scan `ruflo plugins install`
+ * runs on a local plugin before registering it.
+ */
+import { homedir } from 'node:os';
+import { basename, resolve } from 'node:path';
+import { output } from '../output.js';
+import { claudeConfigDir, marketplaceState } from '../mods/plugin-resolve.js';
+import { formatScanFinding, gateScan, scanPluginDir } from '../plugins/marketplace-trust/scan.js';
+import { describeVerification } from '../plugins/marketplace-trust/signature.js';
+import { isUntrusted, verifyClone, verifyInstallCache, writeVerifyStatus } from '../plugins/marketplace-trust/verify-status.js';
+export const verifyCommand = {
+    name: 'verify',
+    description: 'Check ruflo marketplace plugins against their release signatures (verified / modified / unsigned / bad-signature)',
+    options: [
+        { name: 'clone', description: 'A ruflo marketplace checkout to verify instead of the clone Claude Code loads from', type: 'string' },
+        { name: 'no-cache', description: 'Skip the install-cache copies', type: 'boolean', default: false },
+        { name: 'strict', description: 'Exit 1 on unsigned too (default: only modified / bad-signature fail)', type: 'boolean', default: false },
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    examples: [
+        { command: 'ruflo plugins verify', description: 'Every plugin in the ruflo marketplace clone, plus install-cache copies' },
+        { command: 'ruflo plugins verify ruflo-mods', description: 'One plugin' },
+        { command: 'ruflo plugins verify --clone . --strict', description: 'Release check: a checkout must verify completely' },
+    ],
+    action: async (ctx) => {
+        const names = ctx.args.filter((a) => /^[A-Za-z0-9._-]{1,100}$/.test(a));
+        const explicit = ctx.flags.clone ?? undefined;
+        const configDir = claudeConfigDir(process.env, homedir());
+        const clone = explicit ? resolve(explicit) : marketplaceState(configDir).location;
+        if (!clone) {
+            output.printError('No ruflo marketplace clone (run: claude plugin marketplace add ruvnet/ruflo, or pass --clone <dir>)');
+            return { success: false, exitCode: 1 };
+        }
+        let results;
+        try {
+            results = verifyClone(clone, names);
+        }
+        catch (error) {
+            output.printError(`Cannot read ${clone}/.claude-plugin/marketplace.json: ${error.message}`);
+            return { success: false, exitCode: 1 };
+        }
+        if (names.length && results.length === 0) {
+            output.printError(`${names.join(', ')}: not in the marketplace at ${clone}`);
+            return { success: false, exitCode: 1 };
+        }
+        const noCache = ctx.flags.noCache === true || ctx.flags['no-cache'] === true || ctx.flags.cache === false;
+        // The install cache is what Claude Code loads an installed plugin from, so the status the mod's
+        // trust gate reads always includes it (--no-cache only hides it here); an explicit --clone writes nothing.
+        const loadedCache = explicit ? [] : verifyInstallCache(configDir, 'ruflo', names);
+        const cache = noCache ? [] : loadedCache;
+        const statusPath = explicit ? undefined : writeVerifyStatus(configDir, clone, results, undefined, loadedCache);
+        const all = [...results, ...cache];
+        const strict = ctx.flags.strict === true;
+        const failed = all.filter((r) => isUntrusted(r.result) || (strict && r.result === 'unsigned'));
+        if (ctx.flags.json) {
+            output.printJson({ clone, statusPath, clonePlugins: results, installCache: cache });
+        }
+        else {
+            output.writeln(output.dim(`clone: ${clone}`));
+            for (const r of results)
+                printRow(r);
+            if (cache.length)
+                output.writeln(output.dim('install cache:'));
+            for (const r of cache)
+                printRow(r);
+            if (statusPath)
+                output.writeln(output.dim(`status written: ${statusPath}`));
+        }
+        return failed.length ? { success: false, exitCode: 1, data: all } : { success: true, data: all };
+    },
+};
+function printRow(r) {
+    const mark = r.result === 'verified' ? output.success('✓') : r.result === 'unsigned' ? output.warning('!') : output.error('✗');
+    output.writeln(`${mark} ${describeVerification(r)}${r.version ? output.dim(` (v${r.version})`) : ''}`);
+}
+/**
+ * ADR-509 §2.2 for `ruflo plugins install -n <local path>`: a high finding
+ * stops the install unless --accept-risk names the plugin (its directory name).
+ * Returns an error message when the install must stop.
+ */
+export function scanLocalPluginBeforeInstall(dir, acceptRisk) {
+    const name = basename(resolve(dir));
+    const findings = scanPluginDir(name, resolve(dir));
+    for (const f of findings)
+        output.writeln(f.severity === 'high' ? `${output.error('✗')} scan ${formatScanFinding(f)}` : output.dim(`  scan ${formatScanFinding(f)}`));
+    const gate = gateScan(findings, new Set(acceptRisk));
+    if (gate.accepted.length)
+        output.printWarning(`--accept-risk ${name}: installing past its high scan finding(s)`);
+    return gate.blocked.length ? `${name}: high scan finding(s); review them, then re-run with --accept-risk ${name}` : null;
+}
+//# sourceMappingURL=plugins-verify.js.map

package/dist/src/commands/plugins.js

@@ -10,6 +10,9 @@ import { createPluginDiscoveryService, searchPlugins, getPluginSearchSuggestions
 import { getPluginManager } from '../plugins/manager.js';
 import { DEFAULT_PLUGIN_PERMISSIONS, isStrictPluginMode } from '../plugins/trust-policy.js';
 import { getBulkRatings } from '../services/registry-api.js';
+import { scanLocalPluginBeforeInstall, verifyCommand } from './plugins-verify.js';
+import { acceptRiskFrom } from '../plugins/marketplace-trust/scan.js';
+import { pathsCommand } from './plugins-paths.js';
 // List subcommand - Now uses IPFS-based registry
 const listCommand = {
     name: 'list',
@@ -218,6 +221,7 @@ const installCommand = {
             default: true,
         },
         { name: 'trust', type: 'boolean', description: 'Register hooks and commands even if the plugin is untrusted or declares elevated permissions', default: false },
+        { name: 'accept-risk', type: 'string', description: 'Install a local plugin (its directory name) even though the pre-install scan found a high-severity issue in its .mcp.json, hooks/hooks.json or hook modules (ADR-509)' },
         {
             name: 'allow-unverified',
             type: 'boolean',
@@ -270,6 +274,12 @@ const installCommand = {
             let plugin;
             const registryWarnings = [];
             if (isLocalPath) {
+                // ADR-509 §2.2: static scan before anything is registered; a high finding stops the install.
+                const blocked = scanLocalPluginBeforeInstall(name, acceptRiskFrom(ctx.flags));
+                if (blocked) {
+                    spinner.fail(`Refusing to install ${blocked}`);
+                    return { success: false, exitCode: 1 };
+                }
                 // Install from local path
                 spinner.setText(`Installing from ${name}...`);
                 result = await manager.installFromLocal(name, { verify, trust });
@@ -896,7 +906,7 @@ const rateCommand = {
 export const pluginsCommand = {
     name: 'plugins',
     description: 'Plugin management with IPFS-based decentralized registry',
-    subcommands: [listCommand, searchCommand, installCommand, uninstallCommand, upgradeCommand, toggleCommand, infoCommand, createCommand, rateCommand],
+    subcommands: [listCommand, searchCommand, installCommand, uninstallCommand, upgradeCommand, toggleCommand, infoCommand, createCommand, rateCommand, verifyCommand, pathsCommand],
     examples: [
         { command: 'claude-flow plugins list', description: 'List plugins from IPFS registry' },
         { command: 'claude-flow plugins search -q neural', description: 'Search for plugins' },
@@ -917,6 +927,8 @@ export const pluginsCommand = {
             `${output.highlight('upgrade')}   - Upgrade an installed plugin`,
             `${output.highlight('toggle')}    - Enable or disable a plugin`,
             `${output.highlight('info')}      - Show detailed plugin information`,
+            `${output.highlight('verify')}    - Check ruflo marketplace plugins against their release signatures`,
+            `${output.highlight('paths')}     - Local folders of ruflo plugins (claude -p --plugin-dir, Agent SDK)`,
             `${output.highlight('create')}    - Scaffold a new plugin project`,
         ]);
         output.writeln();

package/dist/src/cost/attribution.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `ruflo cost report` (ADR-508 §2.3): which subagent types and tools spent the
+ * money, from the lines the ruflo-mods cost ledger writes to
+ * `.claude-flow/cost/attribution.jsonl` (one per session; see
+ * plugins/ruflo-mods/hooks/cost/attribution.ts `attributionLine`).
+ *
+ * The file is project-writable, so every line is validated to a fixed shape;
+ * a bad line is skipped and counted, never trusted.
+ */
+export declare const ATTRIBUTION_PATH = ".claude-flow/cost/attribution.jsonl";
+export interface AttributionLine {
+    endedAt: number;
+    totalUsd: number;
+    byAgent: Record<string, number>;
+    byTool: Record<string, number>;
+    refusals: number;
+}
+/** One line validated, or undefined. */
+export declare function parseAttributionLine(text: string): AttributionLine | undefined;
+export interface AttributionReport {
+    sessions: number;
+    skipped: number;
+    totalUsd: number;
+    refusals: number;
+    byAgent: [string, number][];
+    byTool: [string, number][];
+}
+/** The report over the file's lines, optionally only sessions that ended at or after `since` (ms). */
+export declare function summarize(text: string, since?: number): AttributionReport;
+/** Reads the project's attribution file; an absent file is an empty report. */
+export declare function readAttribution(cwd: string, since?: number): {
+    report?: AttributionReport;
+    error?: string;
+};
+//# sourceMappingURL=attribution.d.ts.map

package/dist/src/cost/attribution.js

@@ -0,0 +1,101 @@
+/**
+ * `ruflo cost report` (ADR-508 §2.3): which subagent types and tools spent the
+ * money, from the lines the ruflo-mods cost ledger writes to
+ * `.claude-flow/cost/attribution.jsonl` (one per session; see
+ * plugins/ruflo-mods/hooks/cost/attribution.ts `attributionLine`).
+ *
+ * The file is project-writable, so every line is validated to a fixed shape;
+ * a bad line is skipped and counted, never trusted.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const ATTRIBUTION_PATH = '.claude-flow/cost/attribution.jsonl';
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_KEYS = 64;
+const NAME = /^[A-Za-z0-9_.:@/()-]{1,80}$/;
+const MAX_SESSION_USD = 1_000_000;
+function amounts(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value);
+    if (entries.length > MAX_KEYS + 1)
+        return undefined;
+    const out = {};
+    for (const [k, v] of entries) {
+        if (!NAME.test(k) || typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > MAX_SESSION_USD)
+            return undefined;
+        out[k] = v;
+    }
+    return out;
+}
+/** One line validated, or undefined. */
+export function parseAttributionLine(text) {
+    let o;
+    try {
+        o = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!o || typeof o !== 'object' || o.v !== 1)
+        return undefined;
+    const { endedAt, totalUsd, refusals } = o;
+    if (typeof endedAt !== 'number' || !Number.isFinite(endedAt))
+        return undefined;
+    if (typeof totalUsd !== 'number' || !Number.isFinite(totalUsd) || totalUsd < 0 || totalUsd > MAX_SESSION_USD)
+        return undefined;
+    if (typeof refusals !== 'number' || !Number.isInteger(refusals) || refusals < 0)
+        return undefined;
+    const byAgent = amounts(o.byAgent);
+    const byTool = amounts(o.byTool);
+    if (!byAgent || !byTool)
+        return undefined;
+    return { endedAt, totalUsd, byAgent, byTool, refusals };
+}
+const add = (map, record) => {
+    for (const [k, v] of Object.entries(record))
+        map.set(k, (map.get(k) ?? 0) + v);
+};
+const ranked = (map) => [...map].sort((a, b) => b[1] - a[1]);
+/** The report over the file's lines, optionally only sessions that ended at or after `since` (ms). */
+export function summarize(text, since = 0) {
+    const byAgent = new Map();
+    const byTool = new Map();
+    let sessions = 0;
+    let skipped = 0;
+    let totalUsd = 0;
+    let refusals = 0;
+    for (const raw of text.split('\n')) {
+        if (!raw.trim())
+            continue;
+        const line = parseAttributionLine(raw);
+        if (!line) {
+            skipped++;
+            continue;
+        }
+        if (line.endedAt < since)
+            continue;
+        sessions++;
+        totalUsd += line.totalUsd;
+        refusals += line.refusals;
+        add(byAgent, line.byAgent);
+        add(byTool, line.byTool);
+    }
+    return { sessions, skipped, totalUsd, refusals, byAgent: ranked(byAgent), byTool: ranked(byTool) };
+}
+/** Reads the project's attribution file; an absent file is an empty report. */
+export function readAttribution(cwd, since = 0) {
+    const file = path.join(cwd, ATTRIBUTION_PATH);
+    try {
+        const stat = fs.statSync(file);
+        if (stat.size > MAX_FILE_BYTES)
+            return { error: `${ATTRIBUTION_PATH} is over 4 MiB` };
+        return { report: summarize(fs.readFileSync(file, 'utf8'), since) };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return { report: summarize('', since) };
+        return { error: String(error?.message ?? error) };
+    }
+}
+//# sourceMappingURL=attribution.js.map

package/dist/src/cost/budget-file.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The shared budget file (ADR-508 §2.1): `.claude-flow/cost/budget.json`,
+ * version 1. `ruflo cost budget set` writes it; the ruflo-mods cost ladder and
+ * `ruflo cost budget export` read it.
+ *
+ * Second copy of plugins/ruflo-mods/hooks/cost/file.ts (the mod may not import
+ * outside its plugin folder). __tests__/cost-budget-file.test.ts runs both over
+ * the same hostile corpus and requires identical answers.
+ */
+export declare const BUDGET_PATH = ".claude-flow/cost/budget.json";
+export declare const MAX_WINDOWS = 8;
+export declare const MAX_USD = 1000000;
+/** The largest budget file read (a budget is a few hundred bytes). */
+export declare const MAX_FILE_BYTES: number;
+/** LiteLLM's `budget_duration` grammar (`30s`, `30m`, `30h`, `30d`), with a bounded count. */
+export declare const PERIOD: RegExp;
+export interface BudgetWindow {
+    readonly usd: number;
+    readonly period: string;
+}
+export interface BudgetFile {
+    readonly version: 1;
+    readonly windows: readonly BudgetWindow[];
+    readonly hardStop: boolean;
+    readonly fallbackModel?: string;
+}
+export declare const periodSeconds: (period: string) => number;
+/** A budget value validated, or undefined when it breaks any rule (see the mod copy for the list). */
+export declare function validateBudget(value: unknown): BudgetFile | undefined;
+/** The smallest-`usd` window (ties: the shorter period): the one a single session nears first. */
+export declare function ladderWindow(budget: BudgetFile): BudgetWindow;
+export type ReadBudget = {
+    kind: 'absent';
+} | {
+    kind: 'ok';
+    budget: BudgetFile;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+/** Reads and validates the project's budget file. Never throws. */
+export declare function readBudget(cwd: string): ReadBudget;
+export interface BudgetFlags {
+    daily?: unknown;
+    weekly?: unknown;
+    monthly?: unknown;
+    hardStop?: unknown;
+    fallbackModel?: unknown;
+}
+/** A budget from `set` flags (`--daily` 24h, `--weekly` 7d, `--monthly` 30d), or the reason it is not one. */
+export declare function budgetFromFlags(flags: BudgetFlags): {
+    budget?: BudgetFile;
+    error?: string;
+};
+/** Writes the budget file atomically (temp file, rename). Holds no credential. */
+export declare function writeBudget(cwd: string, budget: BudgetFile): string;
+//# sourceMappingURL=budget-file.d.ts.map