@claude-flow/cli 3.63.9 → 3.65.0

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

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.63.9",
+    "version": "3.65.0",
     "files": {
       "auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",
       "hook-handler.cjs": "24502a3bcb78770971147940515c992e35b6736ae14ee2dc54e07d4cdef6a1d8",
@@ -9,6 +9,6 @@
       "router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"
     }
   },
-  "signature": "AuXvfIuEeQvPuxybD+KGB1BhyyvRU6a/3RmXZFXRMdcrpqxujPvNgw83w29VbI6MxMsnBczXqlniGF8iA6+MBg==",
+  "signature": "cwZNQ9x3YdIZ8qur+qzjhgVAubgv3FSXoWEfhkPtNc86sTPBOg6zlIb8Z2bt8ogZ8PnVmNgKas6Ft6QswIBiBg==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-29T14:18:53.918Z",
-  "gitSha": "7f6fb334",
+  "generatedAt": "2026-10-30T02:51:18.963Z",
+  "gitSha": "d000e27e",
   "catalog": {
     "agents": 177,
-    "tools": 444,
+    "tools": 445,
     "skills": 34
   },
   "benchmark": null

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

@@ -0,0 +1,18 @@
+/**
+ * `ruflo cost` — the budget file and gateway export (ADR-508).
+ *
+ *   ruflo cost budget set --daily 10 --monthly 100 [--hard-stop] [--fallback-model haiku]
+ *   ruflo cost budget get
+ *   ruflo cost budget export --gateway litellm [--format json] [--model <gateway model>]   (YAML unless the global --format is json)
+ *   ruflo cost budget export --gateway litellm --apply --url https://proxy --key-env LITELLM_MASTER_KEY
+ *   ruflo cost report [--days 30] [--json]
+ *
+ * Attribution stays in the ruflo-mods cost ledger; enforcement across
+ * sessions and machines belongs to the gateway. The budget file holds no
+ * credential, and the gateway's master key is only ever read from the
+ * environment variable `--key-env` names.
+ */
+import type { Command } from '../types.js';
+export declare const costCommand: Command;
+export default costCommand;
+//# sourceMappingURL=cost.d.ts.map

package/dist/src/commands/cost.js

@@ -0,0 +1,195 @@
+/**
+ * `ruflo cost` — the budget file and gateway export (ADR-508).
+ *
+ *   ruflo cost budget set --daily 10 --monthly 100 [--hard-stop] [--fallback-model haiku]
+ *   ruflo cost budget get
+ *   ruflo cost budget export --gateway litellm [--format json] [--model <gateway model>]   (YAML unless the global --format is json)
+ *   ruflo cost budget export --gateway litellm --apply --url https://proxy --key-env LITELLM_MASTER_KEY
+ *   ruflo cost report [--days 30] [--json]
+ *
+ * Attribution stays in the ruflo-mods cost ledger; enforcement across
+ * sessions and machines belongs to the gateway. The budget file holds no
+ * credential, and the gateway's master key is only ever read from the
+ * environment variable `--key-env` names.
+ */
+import { output } from '../output.js';
+import { BUDGET_PATH, budgetFromFlags, ladderWindow, readBudget, writeBudget } from '../cost/budget-file.js';
+import { applyToLiteLLM, formatBody, gatewayRefusal, keyFromEnv, keyGenerateUrl, maskKey, toLiteLLMKeyBody } from '../cost/litellm.js';
+import { ATTRIBUTION_PATH, readAttribution } from '../cost/attribution.js';
+/** A flag by its camelCase name (the parser's) or its kebab-case spelling. */
+function flag(ctx, name) {
+    const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return ctx.flags[camel] ?? ctx.flags[name];
+}
+const describe = (b) => `${b.windows.map((w) => `$${w.usd} per ${w.period}`).join(', ')}; hard stop ${b.hardStop ? 'on' : 'off'}${b.fallbackModel ? `; fallback ${b.fallbackModel}` : ''}`;
+function loadOrFail(cwd) {
+    const read = readBudget(cwd);
+    if (read.kind === 'ok')
+        return { budget: read.budget };
+    const message = read.kind === 'absent' ? `no budget file at ${BUDGET_PATH}; write one with: ruflo cost budget set --daily 10 --monthly 100` : read.reason;
+    output.printError(message);
+    return { result: { success: false, message, exitCode: 1 } };
+}
+const setSub = {
+    name: 'set',
+    description: 'Write .claude-flow/cost/budget.json (read by the ruflo-mods cost ladder and by export)',
+    options: [
+        { name: 'daily', description: 'USD per 24h window', type: 'string' },
+        { name: 'weekly', description: 'USD per 7d window', type: 'string' },
+        { name: 'monthly', description: 'USD per 30d window', type: 'string' },
+        { name: 'hard-stop', description: 'At 100% of the smallest window, the mod refuses new subagents', type: 'boolean', default: false },
+        { name: 'fallback-model', description: 'Model a gateway falls back to when a per-model budget runs out', type: 'string' },
+    ],
+    action: async (ctx) => {
+        const { budget, error } = budgetFromFlags({
+            daily: flag(ctx, 'daily'), weekly: flag(ctx, 'weekly'), monthly: flag(ctx, 'monthly'),
+            hardStop: flag(ctx, 'hard-stop'), fallbackModel: flag(ctx, 'fallback-model'),
+        });
+        if (!budget) {
+            output.printError(error ?? 'invalid budget');
+            return { success: false, message: error, exitCode: 2 };
+        }
+        const file = writeBudget(ctx.cwd, budget);
+        output.printSuccess(`Budget written to ${file}: ${describe(budget)}`);
+        output.writeln(`The ruflo-mods ladder uses the $${ladderWindow(budget).usd} ${ladderWindow(budget).period} window per session when costBudgetUsd is 0.`);
+        output.writeln('Enforce it across sessions at a gateway: ruflo cost budget export --gateway litellm');
+        return { success: true, data: budget };
+    },
+};
+const getSub = {
+    name: 'get',
+    description: 'Show the budget file',
+    options: [{ name: 'json', description: 'Print JSON', type: 'boolean', default: false }],
+    action: async (ctx) => {
+        const { budget, result } = loadOrFail(ctx.cwd);
+        if (!budget)
+            return result;
+        if (flag(ctx, 'json'))
+            output.printJson(budget);
+        else
+            output.writeln(`${BUDGET_PATH}: ${describe(budget)}`);
+        return { success: true, data: budget };
+    },
+};
+const exportSub = {
+    name: 'export',
+    description: 'Print the budget as gateway key settings (LiteLLM), or --apply it to a proxy',
+    options: [
+        { name: 'gateway', description: 'Gateway: litellm (meta-llm has no documented budget API yet)', type: 'string', required: true },
+        { name: 'model', description: 'Gateway model name for model_max_budget / budget_fallbacks', type: 'string' },
+        { name: 'apply', description: 'POST the budget fields to <url>/key/generate', type: 'boolean', default: false },
+        { name: 'url', description: 'Proxy base URL (https, or http to a loopback host only)', type: 'string' },
+        { name: 'key-env', description: 'Name of the environment variable holding the proxy master key', type: 'string' },
+        { name: 'print-key', description: 'Print the generated virtual key in full (masked by default)', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const refusal = gatewayRefusal(flag(ctx, 'gateway'));
+        if (refusal) {
+            output.printError(refusal);
+            return { success: false, message: refusal, exitCode: 2 };
+        }
+        const { budget, result } = loadOrFail(ctx.cwd);
+        if (!budget)
+            return result;
+        const model = flag(ctx, 'model');
+        let body;
+        try {
+            body = toLiteLLMKeyBody(budget, model === undefined ? undefined : String(model));
+        }
+        catch (error) {
+            const message = String(error.message);
+            output.printError(message);
+            return { success: false, message, exitCode: 2 };
+        }
+        if (!flag(ctx, 'apply')) {
+            // The global --format (text|json|table): json prints the /key/generate body, anything else the YAML key settings.
+            const format = flag(ctx, 'format') === 'json' ? 'json' : 'yaml';
+            output.write(formatBody(body, format));
+            if (model === undefined && budget.fallbackModel) {
+                output.writeErrorln(`note: pass --model <gateway model> to add model_max_budget and budget_fallbacks (-> ${budget.fallbackModel})`);
+            }
+            return { success: true, data: body };
+        }
+        // --apply: every check before anything is sent.
+        const target = keyGenerateUrl(flag(ctx, 'url'));
+        if (!target.url) {
+            output.printError(target.error);
+            return { success: false, message: target.error, exitCode: 2 };
+        }
+        const master = keyFromEnv(flag(ctx, 'key-env'));
+        if (!master.key) {
+            output.printError(master.error);
+            return { success: false, message: master.error, exitCode: 2 };
+        }
+        const applied = await applyToLiteLLM(target.url, master.key, body);
+        if (!applied.ok) {
+            const message = `LiteLLM refused /key/generate (${applied.status || 'no response'}): ${applied.error ?? ''}`;
+            output.printError(message);
+            return { success: false, message, exitCode: 1 };
+        }
+        output.printSuccess(`Budget applied at ${target.url.origin}: a virtual key with ${body.budget_limits.length} budget window(s).`);
+        if (applied.generatedKey) {
+            output.writeln(`Virtual key: ${flag(ctx, 'print-key') ? applied.generatedKey : maskKey(applied.generatedKey)}`);
+            if (!flag(ctx, 'print-key'))
+                output.writeln('(masked; it is shown once by LiteLLM; use --print-key to see it, or look it up in the LiteLLM UI)');
+        }
+        return { success: true, data: { status: applied.status } };
+    },
+};
+const budgetCommand = {
+    name: 'budget',
+    description: 'The shared budget file and its export to a gateway (ADR-508)',
+    subcommands: [setSub, getSub, exportSub],
+    action: getSub.action,
+};
+const reportSub = {
+    name: 'report',
+    description: 'Which subagent types and tools spent the money (from the ruflo-mods cost ledger)',
+    options: [
+        { name: 'days', description: 'Only sessions that ended in the last N days (0: all)', type: 'string', default: '0' },
+        { name: 'json', description: 'Print JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const days = Number(flag(ctx, 'days') ?? 0);
+        const since = Number.isFinite(days) && days > 0 ? Date.now() - days * 86_400_000 : 0;
+        const { report, error } = readAttribution(ctx.cwd, since);
+        if (!report) {
+            output.printError(error ?? 'cannot read the attribution file');
+            return { success: false, message: error, exitCode: 1 };
+        }
+        if (flag(ctx, 'json')) {
+            output.printJson(report);
+            return { success: true, data: report };
+        }
+        if (report.sessions === 0) {
+            output.writeln(`No attributed sessions in ${ATTRIBUTION_PATH}. The ruflo-mods costLedger option (default on) writes one line per session.`);
+            return { success: true, data: report };
+        }
+        const pct = (v) => (report.totalUsd > 0 ? `${((v / report.totalUsd) * 100).toFixed(1)}%` : '-');
+        output.writeln(`${report.sessions} session(s), $${report.totalUsd.toFixed(4)} attributed${report.refusals ? `, ${report.refusals} gateway budget refusal(s)` : ''}${report.skipped ? ` (${report.skipped} unreadable line(s) skipped)` : ''}`);
+        output.writeln('Estimate: each turn\'s cost is split evenly across the tool calls made in it (a turn without tool calls goes to main / (model)).');
+        for (const [title, rows] of [['By agent', report.byAgent], ['By tool', report.byTool]]) {
+            output.writeln('');
+            output.writeln(output.bold(title));
+            output.printTable({
+                columns: [{ key: 'name', header: 'Name', width: 28 }, { key: 'usd', header: 'USD', width: 12, align: 'right' }, { key: 'share', header: 'Share', width: 8, align: 'right' }],
+                data: rows.slice(0, 20).map(([name, usd]) => ({ name, usd: usd.toFixed(4), share: pct(usd) })),
+            });
+        }
+        return { success: true, data: report };
+    },
+};
+export const costCommand = {
+    name: 'cost',
+    description: 'Cost budgets, gateway budget export and per-agent/tool attribution (ADR-508)',
+    subcommands: [budgetCommand, reportSub],
+    examples: [
+        { command: 'ruflo cost budget set --daily 10 --monthly 100', description: 'Write the shared budget file' },
+        { command: 'ruflo cost budget export --gateway litellm', description: 'Print LiteLLM key budget settings (YAML)' },
+        { command: 'ruflo cost budget export --gateway litellm --apply --url https://proxy.example --key-env LITELLM_MASTER_KEY', description: 'Create a budgeted LiteLLM virtual key' },
+        { command: 'ruflo cost report', description: 'Spend by subagent type and by tool' },
+    ],
+    action: reportSub.action,
+};
+export default costCommand;
+//# sourceMappingURL=cost.js.map

package/dist/src/commands/doctor-auto-approve.d.ts

@@ -0,0 +1,9 @@
+export interface AutoApproveCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    message: string;
+    fix?: string;
+}
+export declare const AUTO_APPROVE_CHECK_NAME = "Project auto-approve settings (ADR-509)";
+export declare function checkProjectAutoApproveSettings(cwd?: string): Promise<AutoApproveCheck>;
+//# sourceMappingURL=doctor-auto-approve.d.ts.map

package/dist/src/commands/doctor-auto-approve.js

@@ -0,0 +1,32 @@
+/**
+ * ADR-509 §2.3 — `ruflo doctor` reports project-level auto-approve keys
+ * (enableAllProjectMcpServers, enabledMcpjsonServers, bypassPermissions,
+ * blanket Bash allows, non-ruflo hooks) in `.claude/settings.json` and
+ * `.claude/settings.local.json`, and project `.claude/helpers` that are not
+ * ruflo's signed copies, as a warning, in any project.
+ */
+import { join } from 'node:path';
+import { findPackageHelpersDir } from '../init/helper-refresh.js';
+import { checkRiskySettings, untrustedProjectHelpers } from '../init/risky-settings-gate.js';
+import { formatRiskFindingsAsWarnings } from '../init/settings-risk-scanner.js';
+export const AUTO_APPROVE_CHECK_NAME = 'Project auto-approve settings (ADR-509)';
+export async function checkProjectAutoApproveSettings(cwd = process.cwd()) {
+    const hits = [];
+    for (const file of ['.claude/settings.json', '.claude/settings.local.json']) {
+        const gate = checkRiskySettings(join(cwd, file), 'keep');
+        if (gate)
+            hits.push(...gate.lines.map((l) => `${file}: ${l}`));
+    }
+    // A project-shipped helper that is not ruflo's signed copy runs under ruflo's own hook commands.
+    hits.push(...formatRiskFindingsAsWarnings(untrustedProjectHelpers(cwd, findPackageHelpersDir())));
+    if (hits.length === 0)
+        return { name: AUTO_APPROVE_CHECK_NAME, status: 'pass', message: 'no auto-approve keys in project settings' };
+    const shown = hits.slice(0, 3).join(' | ');
+    return {
+        name: AUTO_APPROVE_CHECK_NAME,
+        status: 'warn',
+        message: `${hits.length} auto-approve key(s): ${shown}${hits.length > 3 ? ` | … ${hits.length - 3} more` : ''}`,
+        fix: 'Review them; `ruflo init upgrade --settings --drop-risky-settings` rewrites settings.json without them',
+    };
+}
+//# sourceMappingURL=doctor-auto-approve.js.map

package/dist/src/commands/doctor.js

@@ -11,6 +11,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { createHash } from 'crypto';
 import { ownInstallAncestors } from '../plugins/own-install.js';
 import { checkNativeAddonHeaders } from './doctor-native-addon.js';
+import { checkProjectAutoApproveSettings } from './doctor-auto-approve.js';
 import { execSync, exec, execFile } from 'child_process';
 import { promisify } from 'util';
 import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
@@ -2322,6 +2323,22 @@ async function checkMods() {
         ? { name: 'ruflo mods (ADR-404)', status: 'pass', message: findings.find((f) => f.name === 'last mod start')?.message ?? 'enabled' }
         : { name: 'ruflo mods (ADR-404)', status: 'warn', message: warnings.map((f) => `${f.name}: ${f.message}`).join('; '), fix: 'ruflo mods doctor' };
 }
+// ADR-510: do ruflo mods run under `claude -p --plugin-dir` here? Spawns a
+// real (cheap) model call, so `--component headless-plugins` only.
+async function checkHeadlessPlugins() {
+    const { checkHeadlessPlugins: run } = await import('../mods/headless-check.js');
+    return run();
+}
+// #4581 / ADR-502: ruflo-mods learning loop — is it recording, and do its verified outcomes reach SONA? Warn-only.
+async function checkLearningLoop() {
+    const { learningLoopHealth } = await import('../memory/verified-outcomes.js');
+    return { name: 'Learning loop (#4581)', ...learningLoopHealth(process.cwd()) };
+}
+// ADR-505: ruflo-mods compaction snapshots hold conversation text; warn when they exist and git does not ignore them.
+async function checkCompactSnapshots() {
+    const { compactSnapshotHealth } = await import('../mods/compact-snapshots.js');
+    return { name: 'Compaction snapshots (ADR-505)', ...compactSnapshotHealth(process.cwd()) };
+}
 // Opt-in @ruvector/typesafe task router (optional peer). `--component typesafe` only.
 async function checkTypesafeRouter() {
     const name = '@ruvector/typesafe router';
@@ -2541,7 +2558,7 @@ export const doctorCommand = {
         {
             name: 'component',
             short: 'c',
-            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, browser, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, mods, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, browser, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, mods, headless-plugins, metaharness)',
             type: 'string'
         },
         {
@@ -2614,6 +2631,7 @@ export const doctorCommand = {
             'browser': checkAgentBrowserVersion,
             'config': checkConfigFile,
             'stale-settings': checkStaleSettingsNpx, // #2448
+            'auto-approve': () => checkProjectAutoApproveSettings(), // ADR-509
             'helpers': helperCheck, // #3565
             'daemon': checkDaemonStatus,
             get memory() {
@@ -2653,6 +2671,9 @@ export const doctorCommand = {
             'auth': checkAuth, // ADR-306
             'typesafe': checkTypesafeRouter, // opt-in @ruvector/typesafe task router
             'mods': checkMods, // ADR-404 — ruflo as a Claude Code mod
+            'learning-loop': checkLearningLoop, // #4581 — verified-outcome learning loop
+            'compact-snapshots': checkCompactSnapshots, // ADR-505 — snapshots must be gitignored
+            'headless-plugins': checkHeadlessPlugins, // ADR-510 — mods under claude -p (spawns claude; not in bare doctor)
         };
         if (component !== undefined && !Object.hasOwn(componentMap, component)) {
             const message = `Unknown doctor component: ${JSON.stringify(component)}. Valid components: ${Object.keys(componentMap).join(', ')}`;
@@ -2740,6 +2761,7 @@ export const doctorCommand = {
             checkGitRepo,
             checkConfigFile,
             checkStaleSettingsNpx, // #2448/#2677 — runaway `npx @latest` in settings
+            () => checkProjectAutoApproveSettings(), // ADR-509 — project auto-approve keys
             helperCheck, // #3565 — installed signed helpers vs manifest
             checkDaemonStatus,
             checkMemoryDatabase,
@@ -2765,6 +2787,8 @@ export const doctorCommand = {
             checkProxySponsoredConsent, // ADR-313 — Meta LLM Proxy sponsored-downtime health
             checkAuth, // ADR-306 — Cognitum identity (warn-only; never fails bare `ruflo doctor`)
             checkMods, // ADR-404 — Claude Code mod path (warn-only)
+            checkLearningLoop, // #4581 — verified outcomes reach SONA (warn-only)
+            checkCompactSnapshots, // ADR-505 — compaction snapshots gitignored (warn-only)
         ];
         let checksToRun = allChecks;
         if (component !== undefined) {
@@ -2778,7 +2802,7 @@ export const doctorCommand = {
             [checkNpmVersion, 'npm'], [checkClaudeCode, 'claude'],
             [checkAgentBrowserVersion, 'browser'], [checkGit, 'git'],
             [checkGitRepo, 'git-repo'], [checkConfigFile, 'config'],
-            [checkStaleSettingsNpx, 'stale-settings'], [helperCheck, 'helpers'],
+            [checkStaleSettingsNpx, 'stale-settings'], [() => checkProjectAutoApproveSettings(), 'auto-approve'], [helperCheck, 'helpers'],
             [checkDaemonStatus, 'daemon'], [checkMemoryDatabase, 'memory-presence'],
             [checkMemoryStructuralIntegrity, 'memory-structural'],
             [checkMemoryIntegrity, 'memory-integrity'],
@@ -2800,6 +2824,8 @@ export const doctorCommand = {
             [checkProxyBinary, 'proxy-binary'], [checkProxyProcess, 'proxy-process'],
             [checkProxyBindAddress, 'proxy-bind'], [checkAuth, 'auth'],
             [checkTypesafeRouter, 'typesafe'], [checkMods, 'mods'],
+            [checkLearningLoop, 'learning-loop'], [checkHeadlessPlugins, 'headless-plugins'],
+            [checkCompactSnapshots, 'compact-snapshots'],
         ]);
         nativeAgentDbChecks.forEach((check, index) => {
             // The path distinguishes simultaneous authority files; normalize separators.

package/dist/src/commands/hive-mind-worker.d.ts

@@ -51,6 +51,8 @@ export interface RunOutcome {
     sessionId?: string;
     costUsd?: number;
     durationMs: number;
+    /** ADR-510 — plugins in the worker profile that could not be found; the run went ahead without them. */
+    missingPlugins?: string[];
 }
 export type TaskRunner = (prompt: string, opts: {
     mcpConfig: string;

package/dist/src/commands/hive-mind-worker.js

@@ -14,6 +14,7 @@ import { spawn as childSpawn } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { resolveClaudeLaunchCommand } from '../runtime/claude-command.js';
+import { withHeadlessPlugins } from '../mods/headless-plugins.js';
 /** The server key the hive-mind prompt addresses (`mcp__ruflo__*`). */
 const RUFLO_SERVER = 'ruflo';
 function readServers(path, cwd) {
@@ -97,7 +98,10 @@ export const runWithClaude = (prompt, opts) => new Promise((resolve) => {
     }
     // The prompt goes on stdin, not argv: a task description has no length
     // bound and `--mcp-config` is variadic (#1780).
-    const child = childSpawn(launch.command, [...launch.argsPrefix, '-p', '--output-format', 'json', `--mcp-config=${opts.mcpConfig}`], { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    // ADR-510: pass the worker profile's plugins (default ruflo-mods) as --plugin-dir.
+    const staged = withHeadlessPlugins([...launch.argsPrefix, '-p', '--output-format', 'json', `--mcp-config=${opts.mcpConfig}`], { ...process.env }, { projectRoot: opts.cwd });
+    const missing = staged.missing.length > 0 ? { missingPlugins: staged.missing } : {};
+    const child = childSpawn(launch.command, staged.argv, { cwd: opts.cwd, env: staged.env, stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (d) => (stdout += d));
@@ -105,7 +109,7 @@ export const runWithClaude = (prompt, opts) => new Promise((resolve) => {
     const timer = setTimeout(() => child.kill('SIGTERM'), opts.timeoutMs);
     child.on('error', (e) => {
         clearTimeout(timer);
-        resolve({ ok: false, output: e.message, exitCode: null, durationMs: Date.now() - started });
+        resolve({ ok: false, output: e.message, exitCode: null, durationMs: Date.now() - started, ...missing });
     });
     child.on('close', (code, signal) => {
         clearTimeout(timer);
@@ -119,11 +123,12 @@ export const runWithClaude = (prompt, opts) => new Promise((resolve) => {
                 sessionId: r.session_id,
                 costUsd: r.total_cost_usd,
                 durationMs,
+                ...missing,
             });
         }
         catch {
             const why = signal === 'SIGTERM' ? `timed out after ${opts.timeoutMs}ms` : (stderr || stdout).trim().slice(-2000);
-            resolve({ ok: false, output: why, exitCode: code, durationMs });
+            resolve({ ok: false, output: why, exitCode: code, durationMs, ...missing });
         }
     });
     child.stdin.end(prompt);
@@ -173,6 +178,7 @@ export async function workOnce(opts) {
         durationMs: outcome.durationMs,
         ...(outcome.sessionId ? { sessionId: outcome.sessionId } : {}),
         ...(outcome.costUsd !== undefined ? { costUsd: outcome.costUsd } : {}),
+        ...(outcome.missingPlugins?.length ? { missingPlugins: outcome.missingPlugins } : {}),
     };
     if (outcome.ok) {
         await callMCPTool('task_complete', { taskId, result });

package/dist/src/commands/hive-mind.js

@@ -13,6 +13,7 @@ import { mkdir, writeFile } from 'fs/promises';
 import { resolveWorkerMcpConfig, currentRufloServer, workCommand } from './hive-mind-worker.js';
 import { join } from 'path';
 import { resolveClaudeLaunchCommand } from '../runtime/claude-command.js';
+import { withHeadlessPlugins } from '../mods/headless-plugins.js';
 import { getHiveTokenForCli } from '../mcp-tools/hive-mind-tools.js';
 // Hive topologies
 const TOPOLOGIES = [
@@ -248,6 +249,18 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
                     output.printWarning('Using --dangerously-skip-permissions for seamless hive-mind execution');
                 }
             }
+            // ADR-510 §2.2: a non-interactive (-p) run is a headless worker and loads
+            // no marketplace plugins on a fresh config, so stage the worker profile
+            // (default ruflo-mods) as --plugin-dir before the prompt. The interactive
+            // path keeps loading plugins the normal, trusted way.
+            let spawnEnv;
+            let missingPlugins = [];
+            if (isNonInteractive) {
+                const staged = withHeadlessPlugins(claudeArgs, { ...process.env }, { projectRoot: process.cwd() });
+                claudeArgs.splice(0, claudeArgs.length, ...staged.argv);
+                spawnEnv = staged.env;
+                missingPlugins = staged.missing;
+            }
             // Add the prompt as the LAST argument
             claudeArgs.push(hiveMindPrompt);
             output.writeln();
@@ -260,6 +273,7 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
             ], {
                 stdio: 'inherit',
                 shell: false,
+                ...(spawnEnv ? { env: spawnEnv } : {}),
             });
             // Set up SIGINT handler for session management
             let isExiting = false;
@@ -312,7 +326,7 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
                 claudeProcess.on('exit', (c) => resolve(c ?? 0));
                 claudeProcess.on('error', () => resolve(1));
             });
-            return { success: claudeExitCode === 0, promptFile };
+            return { success: claudeExitCode === 0, promptFile, ...(missingPlugins.length > 0 ? { missingPlugins } : {}) };
         }
         else if (dryRun) {
             output.writeln();

package/dist/src/commands/hooks.js

@@ -4649,6 +4649,49 @@ const refreshAdvisorCommand = {
         }
     }
 };
+// #4581 / ADR-502: fold the ruflo-mods learning loop's verified outcomes into SONA.
+const verifiedIngestCommand = {
+    name: 'verified-ingest',
+    description: 'Train SONA from the learning loop\'s verified turns (tests/build exit status); unverified turns never train',
+    options: [
+        { name: 'dry-run', description: 'Count only: train nothing and write nothing', type: 'boolean', default: false },
+        { name: 'force', description: 'Re-read the file even if unchanged since the last ingest', type: 'boolean', default: false },
+    ],
+    examples: [
+        { command: 'ruflo hooks verified-ingest', description: 'Ingest new verified outcomes and refresh learned-lessons.json' },
+        { command: 'ruflo hooks verified-ingest --dry-run', description: 'Show what would be trained' },
+    ],
+    action: async (ctx) => {
+        try {
+            const result = await callMCPTool('hooks_intelligence_verified-ingest', { dryRun: ctx.flags['dry-run'] === true || ctx.flags.dryRun === true, force: ctx.flags.force === true });
+            if (ctx.flags.format === 'json') {
+                output.printJson(result);
+                return { success: true, data: result };
+            }
+            if (result.skipped === 'no-file') {
+                output.printInfo('No recorded turns yet (.claude-flow/data/verified-trajectories.jsonl). Turn on the ruflo-mods learningLoop option.');
+                return { success: true, data: result };
+            }
+            if (!result.sonaAvailable)
+                output.printWarning('SONA unavailable: verified outcomes wait for the next ingest');
+            const i = result.ingested;
+            output.printSuccess(`Ingested ${i.verifiedSuccess} verified success, ${i.verifiedFailure} verified failure; ${i.unknown} unverified (not trained), ${i.tainted ?? 0} tainted (not trained), ${i.rejected} malformed${result.skipped === 'unchanged' ? ' (file unchanged)' : ''}`);
+            output.writeln(`Lessons at or above the 0.6 gate: ${result.lessons}; cautions: ${result.cautions}; verified patterns below the gate: ${result.belowGate}`);
+            // ADR-503 §2.4: patterns the anomaly gate kept out of the prompt (they stay in SONA).
+            for (const h of result.held ?? [])
+                output.writeln(`held: ${h.id} (${h.reason})`);
+            const rv = result.reverify;
+            if (rv?.enabled)
+                output.writeln(`Re-verify: ${rv.ran} check(s) run, ${rv.passed} passed, ${rv.downgraded} downgraded to unverified${rv.deferred ? `, ${rv.deferred} waiting` : ''}`);
+            output.writeln(output.dim(`All time: ${result.totals.verifiedSuccess} success / ${result.totals.verifiedFailure} failure trained, ${result.totals.unknown} unverified, ${result.totals.tainted ?? 0} tainted`));
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`verified-ingest failed: ${error instanceof Error ? error.message : String(error)}`);
+            return { success: false, exitCode: 1 };
+        }
+    },
+};
 // Main hooks command
 export const hooksCommand = {
     name: 'hooks',
@@ -4696,6 +4739,8 @@ export const hooksCommand = {
         refreshFunnelCommand,
         // Advisor co-pilot tip background refresh — ADR-316
         refreshAdvisorCommand,
+        // Verified-outcome learning loop — #4581
+        verifiedIngestCommand,
     ],
     options: [],
     examples: [

package/dist/src/commands/index.js

@@ -92,6 +92,8 @@ const commandLoaders = {
     advisor: () => import('./advisor.js'),
     // Ruflo verbs in Claude Code's spinnerVerbs rotation (ADR-318)
     spinner: () => import('./spinner.js'),
+    // Budget file, gateway budget export and per-agent/tool cost attribution (ADR-508)
+    cost: () => import('./cost.js'),
     // ruflo as a Claude Code mod: function hooks, early access (ADR-404)
     mods: () => import('./mods.js'),
     // ADR-489: the console in a terminal of its own (read-only Overview and Cost); loads a bundle from this CLI's own install.