@claude-flow/cli 3.56.9 → 3.57.0

package/dist/src/commands/tui.js

@@ -34,6 +34,20 @@ function cliEntry() {
     const entry = join(__dirname, '..', '..', '..', 'bin', 'cli.js');
     return existsSync(entry) ? entry : undefined;
 }
+/** The look and motion flags: `--look bbs|orbital|plain` (default bbs, as in the console), `--fps N` (0-30, default 8; 0 draws pictures still), `--no-anim`, `--no-pictures`. A bad value is ignored, never passed on. */
+export function lookFlags(flags) {
+    const look = flags?.look;
+    const fps = flags?.fps;
+    const number = typeof fps === 'number' ? fps : typeof fps === 'string' && /^\d{1,2}$/.test(fps) ? Number(fps) : undefined;
+    return {
+        ...(look === 'bbs' || look === 'orbital' || look === 'plain' ? { look } : {}),
+        ...(number !== undefined && Number.isFinite(number) && number >= 0 && number <= 30 ? { fps: Math.floor(number) } : {}),
+        ...(flags?.anim === false ? { anim: false } : {}),
+        ...(flags?.pictures === false ? { pictures: false } : {}),
+        ...(flags?.boot === true ? { boot: true } : {}),
+        ...(flags?.mouse === true ? { mouse: true } : {}),
+    };
+}
 /** The AI page's settings from the flags (and one environment variable for the endpoint list). Absent flags leave the defaults; a bad number is ignored, never passed on. */
 export function aiPage(flags) {
     const model = typeof flags?.model === 'string' && flags.model !== '' ? flags.model : undefined;
@@ -46,11 +60,17 @@ export const tuiCommand = {
     name: 'tui',
     description: 'The ruflo console in your terminal: Overview, Cost, Swarm, Events, Missions (read-only) and an AI page that asks Codex or OpenRouter, each question after a card.',
     options: [
-        { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string', default: 'overview' },
+        { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}, or any console view (menu, federation, settings, ...): 0 opens the menu and : goes to a page by name`, type: 'string', default: 'overview' },
         { name: 'ai', description: 'The AI page (ask Codex read-only or OpenRouter, each question after a confirm card). --no-ai turns it off', type: 'boolean', default: true },
         { name: 'model', description: 'OpenRouter model for this session (default openrouter/auto)', type: 'string' },
         { name: 'max-spend-usd', description: 'Stop sending to OpenRouter once the provider-reported spend reaches this (default 0.5)', type: 'number' },
         { name: 'convo-targets', description: 'Extra OpenAI-compatible endpoints, the console convoTargets syntax: endpoint:<name>=<https-base-url>|<KEY_ENV>|<model>;... (a key is named by its environment variable). Also RUFLO_TUI_CONVO_TARGETS', type: 'string' },
+        { name: 'look', description: 'The console look: bbs (default, as in Claude Code) | orbital | plain. Key t cycles them', type: 'string' },
+        { name: 'fps', description: 'Frames per second for moving pictures, 0-30 (default 8; 0 draws every picture still)', type: 'number' },
+        { name: 'anim', description: 'Animate the pictures. --no-anim draws them still', type: 'boolean', default: true },
+        { name: 'pictures', description: 'Draw the pictures of the console (title art, swarm graph, gauges). --no-pictures shows their words only', type: 'boolean', default: true },
+        { name: 'mouse', description: 'Read mouse reports: click a page in the bar, scroll with the wheel (every action also has a key)', type: 'boolean', default: false },
+        { name: 'boot', description: 'Play the look\'s start-up screen first (as the console\'s boot setting)', type: 'boolean', default: false },
         { name: 'plain', description: 'Print one frame as plain text and exit 0 (scripts and CI). Without it, a non-terminal gets a hint and exit 2', type: 'boolean', default: false },
     ],
     examples: [
@@ -62,7 +82,9 @@ export const tuiCommand = {
     async action(context) {
         const ctx = context;
         const wanted = ctx.flags?.view ?? ctx.args?.find(arg => !arg.startsWith('-')) ?? 'overview';
-        if (!VIEWS.includes(wanted)) {
+        // The six pages are known here; any other console view (menu, federation, settings, …) is checked against the bundle's own list once it is loaded.
+        const isKnown = VIEWS.includes(wanted);
+        if (!isKnown && !/^[a-z]{2,16}$/.test(wanted)) {
             output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}`));
             return { success: false, exitCode: 2, data: { error: 'unknown-view' } };
         }
@@ -80,12 +102,16 @@ export const tuiCommand = {
             output.writeln(output.error(`tui: could not load the console bundle: ${error instanceof Error ? error.message.slice(0, 160) : 'unknown error'}`));
             return { success: false, exitCode: 1, data: { error: 'bundle-load-failed' } };
         }
+        if (!isKnown && mod.isPage?.(wanted) !== true) {
+            output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}, or any console view such as menu, federation, settings`));
+            return { success: false, exitCode: 2, data: { error: 'unknown-view' } };
+        }
         const stop = new AbortController();
         const onSignal = () => stop.abort();
         process.once('SIGTERM', onSignal);
         process.once('SIGHUP', onSignal);
         try {
-            const code = await mod.runTui({ cwd: ctx.cwd ?? process.cwd(), view: wanted, ...(ctx.flags?.plain === true && { plain: true }), ...(ctx.flags?.ai !== false && { aiPage: aiPage(ctx.flags) }), ...(cliEntry() !== undefined && { cliEntry: cliEntry() }), ...(process.env.CLAUDE_CONFIG_DIR !== undefined && { configDir: process.env.CLAUDE_CONFIG_DIR }) }, { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env, signal: stop.signal });
+            const code = await mod.runTui({ cwd: ctx.cwd ?? process.cwd(), view: wanted, ...lookFlags(ctx.flags), ...(ctx.flags?.plain === true && { plain: true }), ...(ctx.flags?.ai !== false && { aiPage: aiPage(ctx.flags) }), ...(cliEntry() !== undefined && { cliEntry: cliEntry() }), ...(process.env.CLAUDE_CONFIG_DIR !== undefined && { configDir: process.env.CLAUDE_CONFIG_DIR }) }, { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env, signal: stop.signal });
             return { success: code === 0, exitCode: code };
         }
         finally {

package/dist/src/config/proven-config-refresh.d.ts

@@ -15,6 +15,15 @@ export declare const ADOPTED_CONFIG_FILE = "proven-config.json";
 export declare function loadShippedChampion(srcPath: string): SignedProvenConfig | null;
 /** Build the local environment the champion's constraints are checked against. */
 export declare function currentInstallEnv(cwd?: string): InstallEnv;
+/**
+ * #4176: is `cwd` a ruflo project? A bare `.claude/` is not enough: Claude Code
+ * itself creates `.claude/.cc-writes/` in whatever directory a Bash command ran
+ * in, so every subdirectory a session cd-ed into used to qualify and received a
+ * proven-config.json. A ruflo project carries `ruflo init`'s own markers: a
+ * `.claude/settings.json`, the `.claude/helpers/` directory, or an earlier
+ * adoption stamp.
+ */
+export declare function isRufloProject(cwd: string): boolean;
 export interface AdoptResult {
     adopted: boolean;
     from?: string;

package/dist/src/config/proven-config-refresh.js

@@ -84,6 +84,27 @@ export function currentInstallEnv(cwd = process.cwd()) {
     catch { /* none */ }
     return env;
 }
+/**
+ * #4176: is `cwd` a ruflo project? A bare `.claude/` is not enough: Claude Code
+ * itself creates `.claude/.cc-writes/` in whatever directory a Bash command ran
+ * in, so every subdirectory a session cd-ed into used to qualify and received a
+ * proven-config.json. A ruflo project carries `ruflo init`'s own markers: a
+ * `.claude/settings.json`, the `.claude/helpers/` directory, or an earlier
+ * adoption stamp.
+ */
+export function isRufloProject(cwd) {
+    try {
+        const claudeDir = path.join(cwd, '.claude');
+        if (!fs.statSync(claudeDir).isDirectory())
+            return false;
+        return fs.existsSync(path.join(claudeDir, 'settings.json'))
+            || fs.existsSync(path.join(claudeDir, 'helpers'))
+            || fs.existsSync(path.join(claudeDir, PROVEN_CONFIG_STAMP));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The testable adoption core: given a signed champion and the local env, adopt
  * it into `cwd/.claude` iff it is newer than the stamp AND passes both gates.
@@ -92,8 +113,8 @@ export function currentInstallEnv(cwd = process.cwd()) {
 export function adoptSignedConfig(cwd, signed, env, opts = {}) {
     try {
         const claudeDir = path.join(cwd, '.claude');
-        if (!fs.existsSync(claudeDir))
-            return { adopted: false }; // not a ruflo project
+        if (!isRufloProject(cwd))
+            return { adopted: false }; // not a ruflo project (#4176)
         const championId = signed.manifest?.policy?.ref;
         if (!championId)
             return { adopted: false, skipped: 'manifest missing policy.ref' };
@@ -137,7 +158,7 @@ export function adoptSignedConfig(cwd, signed, env, opts = {}) {
  */
 export async function autoAdoptProvenConfigIfStale(cwd = process.cwd()) {
     try {
-        if (!fs.existsSync(path.join(cwd, '.claude')))
+        if (!isRufloProject(cwd))
             return { adopted: false };
         const src = findPackageProvenConfig();
         if (!src)

package/dist/src/funnel/local-signals.js

@@ -34,7 +34,8 @@ export function getSecurityStatus(cwd = process.cwd()) {
         const rawFindings = scan.summary?.total ?? scan.totalFindings ?? scan.findings?.length ?? 0;
         const findings = Math.max(0, Number.isFinite(rawFindings) ? rawFindings : 0);
         return {
-            status: findings > 0 ? 'ISSUES' : 'CLEAN',
+            // #4124: a scan whose dependency phase could not run is not a clean scan.
+            status: findings > 0 ? 'ISSUES' : scan.incomplete === true ? 'PENDING' : 'CLEAN',
             findings,
             scannedAt: typeof scan.timestamp === 'string' ? scan.timestamp : undefined,
             cvesFixed: 0,

package/dist/src/index.js

@@ -16,6 +16,7 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { commandParser } from './parser.js';
 import { output } from './output.js';
+import { resolveTargetCommand } from './command-resolution.js';
 import { commands, getCommandsByCategory, getCommand, getCommandAsync, getCommandNames, getLazyCommandNames, hasCommand } from './commands/index.js';
 import { suggestCommand } from './suggest.js';
 import { runStartupUpdateCheck } from './update/index.js';
@@ -91,13 +92,13 @@ export class CLI {
             const parseResult = this.parser.parse(args);
             const { command: commandPath, flags, positional } = parseResult;
             // Handle global flags
+            if (flags.noColor || flags.color === false) {
+                this.output.setColorEnabled(false);
+            }
             if (flags.version || flags.V) {
                 this.showVersion();
                 return;
             }
-            if (flags.noColor) {
-                this.output.setColorEnabled(false);
-            }
             // Set verbosity level based on flags
             if (flags.quiet) {
                 this.output.setVerbosity('quiet');
@@ -113,7 +114,7 @@ export class CLI {
                 this.output.printDebug(`CWD: ${process.cwd()}`);
             }
             // Run startup update check (non-blocking, silent on skip)
-            if (!flags.noUpdate && commandPath[0] !== 'update') {
+            if (!flags.noUpdate && flags.update !== false && commandPath[0] !== 'update' && !(commandPath[0] === 'doctor' && flags.json)) {
                 this.checkForUpdatesOnStartup().catch(() => { });
             }
             // Version-stamped helper auto-refresh — propagate hook fixes to an already
@@ -264,48 +265,11 @@ export class CLI {
                 this.output.writeln(this.output.dim(`  ${message}`));
                 process.exit(1);
             }
-            // Handle subcommand (supports nested subcommands)
-            let targetCommand = command;
-            let subcommandArgs = positional;
-            // Process command path (e.g., ['hooks', 'worker', 'list'])
-            // Note: When parser includes subcommand in commandPath, positional already excludes it
-            if (commandPath.length > 1 && command.subcommands) {
-                const subcommandName = commandPath[1];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    // Parser already extracted subcommand from positional, so use as-is
-                    subcommandArgs = positional;
-                    // Check for nested subcommand (level 2)
-                    if (commandPath.length > 2 && subcommand.subcommands) {
-                        const nestedName = commandPath[2];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            // Parser already extracted nested subcommand too
-                            subcommandArgs = positional;
-                        }
-                    }
-                }
-            }
-            else if (positional.length > 0 && command.subcommands) {
-                // Check if first positional is a subcommand
-                const subcommandName = positional[0];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    subcommandArgs = positional.slice(1);
-                    // Check for nested subcommand (level 2 from positional)
-                    if (subcommandArgs.length > 0 && subcommand.subcommands) {
-                        const nestedName = subcommandArgs[0];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            subcommandArgs = subcommandArgs.slice(1);
-                        }
-                    }
-                }
-            }
+            // Handle subcommands at any depth (#4157): walk the parsed command path, or the
+            // positional arguments when the path only names the top-level command.
+            const resolved = resolveTargetCommand(command, commandPath, positional);
+            const targetCommand = resolved.target;
+            const subcommandArgs = resolved.args;
             // Validate flags
             const validationErrors = this.parser.validateFlags(flags, targetCommand);
             if (validationErrors.length > 0) {
@@ -572,7 +536,7 @@ export class CLI {
         catch (error) {
             // Config loading is optional - don't fail if it doesn't exist
             if (process.env.DEBUG) {
-                this.output.writeln(this.output.dim(`Config loading failed: ${error.message}`));
+                this.output.writeErrorln(this.output.dim(`Config loading failed: ${error.message}`));
             }
             return undefined;
         }

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

@@ -27,7 +27,6 @@ export function generateSettings(options) {
         allow: [
             'Bash(npx @claude-flow*)',
             'Bash(npx claude-flow*)',
-            'Bash(node .claude/*)',
             'mcp__claude-flow__*',
         ],
         deny: [
@@ -201,7 +200,7 @@ function generateHooksConfig(config, scope) {
     const hooks = {};
     // Node.js scripts handle errors internally via try/catch.
     // No shell-level error suppression needed (2>/dev/null || true breaks Windows).
-    // PreToolUse — validate commands and edits before execution
+    // PreToolUse — validate shell commands before execution
     if (config.preToolUse) {
         hooks.PreToolUse = [
             {
@@ -214,19 +213,9 @@ function generateHooksConfig(config, scope) {
                     },
                 ],
             },
-            {
-                matcher: 'Write|Edit|MultiEdit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('pre-edit', scope),
-                        timeout: config.timeout,
-                    },
-                ],
-            },
         ];
     }
-    // PostToolUse — record edits and commands for session metrics / learning
+    // PostToolUse — record edits for session metrics / learning
     if (config.postToolUse) {
         hooks.PostToolUse = [
             {
@@ -239,16 +228,6 @@ function generateHooksConfig(config, scope) {
                     },
                 ],
             },
-            {
-                matcher: 'Bash',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('post-bash', scope),
-                        timeout: config.timeout,
-                    },
-                ],
-            },
         ];
     }
     // UserPromptSubmit — intelligent task routing
@@ -312,16 +291,13 @@ function generateHooksConfig(config, scope) {
             },
         ];
     }
-    // PreCompact — preserve context before compaction
+    // PreCompact — end the current session before compaction. The handler has no
+    // manual/automatic compaction-specific command, so don't wire no-op hooks.
     if (config.preCompact) {
         hooks.PreCompact = [
             {
                 matcher: 'manual',
                 hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('compact-manual', scope),
-                    },
                     {
                         type: 'command',
                         command: hookHandlerCmd('session-end', scope),
@@ -332,10 +308,6 @@ function generateHooksConfig(config, scope) {
             {
                 matcher: 'auto',
                 hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('compact-auto', scope),
-                    },
                     {
                         type: 'command',
                         command: hookHandlerCmd('session-end', scope),
@@ -345,18 +317,6 @@ function generateHooksConfig(config, scope) {
             },
         ];
     }
-    // SubagentStart — status update when a sub-agent is spawned
-    hooks.SubagentStart = [
-        {
-            hooks: [
-                {
-                    type: 'command',
-                    command: hookHandlerCmd('status', scope),
-                    timeout: 3000,
-                },
-            ],
-        },
-    ];
     // SubagentStop — track agent completion for metrics
     // NOTE: The valid event is "SubagentStop" (not "SubagentEnd")
     hooks.SubagentStop = [
@@ -370,20 +330,6 @@ function generateHooksConfig(config, scope) {
             ],
         },
     ];
-    // Notification — capture Claude Code notifications for logging
-    if (config.notification) {
-        hooks.Notification = [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('notify', scope),
-                        timeout: 3000,
-                    },
-                ],
-            },
-        ];
-    }
     // NOTE: TeammateIdle, TaskCompleted, and PostCompact are NOT accepted by
     // Claude Code's settings.json validator (rejected as "Invalid key in record").
     // Agent Teams coordination lives in claudeFlow.agentTeams.hooks instead.

package/dist/src/init/types.js

@@ -76,7 +76,7 @@ export const DEFAULT_INIT_OPTIONS = {
         github: true,
         flowNexus: false,
         browser: true,
-        v3: true,
+        v3: false, // ADR-128: opt-in like agents.v3; use --full or `init skills --v3`
         dualMode: false, // Optional: enable with --dual flag
         all: false,
     },

package/dist/src/mcp-tools/agent-execute-core.d.ts

@@ -7,6 +7,7 @@
  * keeps the wire from agent_spawn → ProviderManager (real) in one
  * place rather than duplicated.
  */
+import { type AgentExecutionSample } from './agent-health-metrics.js';
 type ClaudeModel = 'haiku' | 'sonnet' | 'opus' | 'opus-4.7' | 'inherit';
 export interface AgentRecord {
     agentId: string;
@@ -32,6 +33,7 @@ export interface AgentRecord {
     /** ADR-148 phase 2 — concrete OpenRouter slug when provider='openrouter'. */
     openrouterModel?: string;
     lastResult?: Record<string, unknown>;
+    executionHistory?: AgentExecutionSample[];
 }
 export declare const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-5";
 export declare function modelRejectsSamplingParams(model: string): boolean;

package/dist/src/mcp-tools/agent-execute-core.js

@@ -10,6 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
+import { appendAgentExecution, summarizeAgentExecutions } from './agent-health-metrics.js';
 import { configManager } from '../services/config-file-manager.js';
 const STORAGE_DIR = '.claude-flow';
 const AGENT_DIR = 'agents';
@@ -669,6 +670,20 @@ export async function executeAgentTask(input) {
             }
             if (out)
                 current.lastResult = out;
+            const previousMeasuredHealth = summarizeAgentExecutions(current.executionHistory).health;
+            const mayUpdateStoredHealth = previousMeasuredHealth === null
+                ? current.health === agent.health
+                : current.health === previousMeasuredHealth;
+            current.executionHistory = appendAgentExecution(current.executionHistory, {
+                at: new Date().toISOString(),
+                success: result.success,
+                durationMs: result.durationMs ?? Date.now() - startedAt,
+            });
+            // An explicit agent_update during the provider call still wins. The
+            // measured value remains available from executionHistory in agent_health.
+            if (mayUpdateStoredHealth) {
+                current.health = summarizeAgentExecutions(current.executionHistory).health ?? current.health;
+            }
             saveAgentStore(latest);
         };
         if (result.success) {

package/dist/src/mcp-tools/agent-health-metrics.d.ts

@@ -0,0 +1,22 @@
+/** Bounded execution evidence for agent_health. Registry records are not processes. */
+export interface AgentExecutionSample {
+    at: string;
+    success: boolean;
+    durationMs: number;
+}
+export declare const AGENT_HEALTH_WINDOW = 20;
+export declare function appendAgentExecution(value: unknown, sample: AgentExecutionSample): AgentExecutionSample[];
+export declare function summarizeAgentExecutions(value: unknown): {
+    health: number | null;
+    errorRate: number | null;
+    sampleCount: number;
+    successes: number;
+    failures: number;
+    latency: {
+        avg: number | null;
+        p50: number | null;
+        p95: number | null;
+        p99: number | null;
+    };
+};
+//# sourceMappingURL=agent-health-metrics.d.ts.map

package/dist/src/mcp-tools/agent-health-metrics.js

@@ -0,0 +1,33 @@
+export const AGENT_HEALTH_WINDOW = 20;
+function validSamples(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((sample) => sample !== null && typeof sample === 'object' &&
+        typeof sample.at === 'string' && typeof sample.success === 'boolean' &&
+        typeof sample.durationMs === 'number' && Number.isFinite(sample.durationMs) && sample.durationMs >= 0).slice(-AGENT_HEALTH_WINDOW);
+}
+export function appendAgentExecution(value, sample) {
+    return [...validSamples(value), sample].slice(-AGENT_HEALTH_WINDOW);
+}
+export function summarizeAgentExecutions(value) {
+    const samples = validSamples(value);
+    const sampleCount = samples.length;
+    const successes = samples.filter(sample => sample.success).length;
+    const failures = sampleCount - successes;
+    const durations = samples.map(sample => sample.durationMs).sort((a, b) => a - b);
+    const percentile = (p) => sampleCount ? durations[Math.ceil(p * sampleCount) - 1] : null;
+    return {
+        health: sampleCount ? successes / sampleCount : null,
+        errorRate: sampleCount ? failures / sampleCount : null,
+        sampleCount,
+        successes,
+        failures,
+        latency: {
+            avg: sampleCount ? durations.reduce((sum, duration) => sum + duration, 0) / sampleCount : null,
+            p50: percentile(0.5),
+            p95: percentile(0.95),
+            p99: percentile(0.99),
+        },
+    };
+}
+//# sourceMappingURL=agent-health-metrics.js.map

package/dist/src/mcp-tools/agent-tools.js

@@ -10,6 +10,7 @@ import { readRecordStore } from './record-store.js';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';
 import { executeAgentTask } from './agent-execute-core.js';
+import { AGENT_HEALTH_WINDOW, summarizeAgentExecutions } from './agent-health-metrics.js';
 import { pheromoneAgentEligibility } from './swarm-tools.js';
 // Storage paths
 const STORAGE_DIR = '.claude-flow';
@@ -691,7 +692,7 @@ export const agentTools = [
     },
     {
         name: 'agent_health',
-        description: 'Compute an agent\'s rolling health score (0-1) from recent task success ratio + response-latency p50/p95 + error rate. Use when native Task tool is wrong because you\'re running a long-lived agent (autonomous loop / hive-mind worker / federation peer) and need to detect degradation before the breaker trips it. For one-shot Task invocations there is no history to score. Pair with hooks_post-task so the scores stay current.',
+        description: 'Report measured agent_execute provider-call outcomes over the last 20 calls: API success-ratio health (0-1), error rate, and response-latency p50/p95. This does not measure task correctness. Agents with no observed calls have unknown health; registration is not proof of a running process. Native Task and hooks_post-task outcomes are not recorded here. Use when you need measured reliability for agents driven through agent_execute; native Task results are invisible to this tool, so inspect those directly.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -708,58 +709,80 @@ export const agentTools = [
             }
             const store = loadAgentStore();
             const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
-            const threshold = input.threshold || 0.5;
+            const threshold = input.threshold === undefined ? 0.5 : input.threshold;
+            if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+                return { error: 'threshold must be a finite number between 0 and 1' };
+            }
+            const healthStatus = (health) => health === null ? 'unknown' : health >= threshold ? 'healthy' : health >= 0.3 ? 'degraded' : 'unhealthy';
             if (input.agentId) {
                 const agent = store.agents[input.agentId];
                 if (agent) {
+                    const metrics = summarizeAgentExecutions(agent.executionHistory);
                     return {
                         agentId: agent.agentId,
-                        health: agent.health,
+                        ...metrics,
+                        healthStatus: healthStatus(metrics.health),
                         status: agent.status,
-                        healthy: agent.health >= threshold,
+                        healthy: metrics.health === null ? null : metrics.health >= threshold,
                         taskCount: agent.taskCount,
-                        uptime: Date.now() - new Date(agent.createdAt).getTime(),
+                        uptime: null,
+                        registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),
+                        windowSize: AGENT_HEALTH_WINDOW,
+                        source: 'agent_execute',
                     };
                 }
                 return { agentId: input.agentId, error: 'Agent not found' };
             }
-            const healthyAgents = agents.filter(a => a.health >= threshold);
-            const degradedAgents = agents.filter(a => a.health >= 0.3 && a.health < threshold);
-            const unhealthyAgents = agents.filter(a => a.health < 0.3);
-            const avgHealth = agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 1;
+            const observed = agents.map(agent => ({ agent, metrics: summarizeAgentExecutions(agent.executionHistory) }));
+            const healthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'healthy');
+            const degradedAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'degraded');
+            const unhealthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'unhealthy');
+            const measuredAgents = observed.filter(({ metrics }) => metrics.health !== null);
+            const unknownCount = agents.length - measuredAgents.length;
+            const avgHealth = measuredAgents.length > 0
+                ? measuredAgents.reduce((sum, { metrics }) => sum + metrics.health, 0) / measuredAgents.length
+                : null;
             return {
                 // CLI expected fields
-                agents: agents.map(a => {
-                    const uptime = Date.now() - new Date(a.createdAt).getTime();
+                agents: observed.map(({ agent, metrics }) => {
                     return {
-                        id: a.agentId,
-                        type: a.agentType,
-                        health: a.health >= threshold ? 'healthy' : (a.health >= 0.3 ? 'degraded' : 'unhealthy'),
-                        uptime,
-                        tasks: { active: a.taskCount > 0 ? 1 : 0, queued: 0, completed: a.taskCount, failed: 0 },
-                        _note: 'Per-agent OS metrics not available — use system_metrics for real CPU/memory',
+                        id: agent.agentId,
+                        type: agent.agentType,
+                        health: healthStatus(metrics.health),
+                        score: metrics.health,
+                        sampleCount: metrics.sampleCount,
+                        errorRate: metrics.errorRate,
+                        latency: metrics.latency,
+                        errors: { count: metrics.failures },
+                        uptime: null,
+                        registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),
+                        tasks: { active: agent.status === 'busy' ? 1 : 0, queued: null, completed: metrics.successes, failed: metrics.failures },
+                        _note: `Provider-call outcomes and latency cover only the last ${AGENT_HEALTH_WINDOW} agent_execute calls; task correctness, process liveness and CPU/memory are not observed`,
                     };
                 }),
                 overall: {
                     healthy: healthyAgents.length,
                     degraded: degradedAgents.length,
                     unhealthy: unhealthyAgents.length,
+                    unknown: unknownCount,
                     cpu: null,
                     memory: null,
                     _note: 'Per-agent CPU/memory not available — use system_metrics for real OS-level stats',
-                    score: Math.round(avgHealth * 100),
+                    score: avgHealth === null ? null : Math.round(avgHealth * 100),
                     issues: unhealthyAgents.length,
                 },
                 // Additional fields
                 total: agents.length,
+                observedCount: measuredAgents.length,
+                unknownCount,
                 healthyCount: healthyAgents.length,
                 unhealthyCount: unhealthyAgents.length,
                 threshold,
                 avgHealth,
-                unhealthyAgents: unhealthyAgents.map(a => ({
-                    agentId: a.agentId,
-                    health: a.health,
-                    status: a.status,
+                unhealthyAgents: unhealthyAgents.map(({ agent, metrics }) => ({
+                    agentId: agent.agentId,
+                    health: metrics.health,
+                    status: agent.status,
                 })),
             };
         },

package/dist/src/mcp-tools/agentbbs-federation.d.ts

@@ -50,7 +50,7 @@
  *
  * @module @claude-flow/cli/mcp-tools/agentbbs-federation
  */
-import { type Server } from 'node:http';
+import type { Server } from 'node:http';
 /** Max envelopes accepted from one peer in one sync. */
 export declare const MAX_ENVELOPES_PER_SYNC = 5000;
 /** Max serialized bytes for a single envelope. */

package/dist/src/mcp-tools/agentbbs-federation.js

@@ -53,7 +53,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+// Lazy, CommonJS-style load of node:http: an ESM `import … from 'node:http'`
+// materialises every export of the builtin, which trips http's lazy undici
+// getters (~2.5 MB heap / ~6 MB RSS) at MCP startup even when no server is
+// ever started. require() of the builtin does not touch those getters.
+const loadHttp = () => createRequire(import.meta.url)('node:http');
 /** Max envelopes accepted from one peer in one sync. */
 export const MAX_ENVELOPES_PER_SYNC = 5_000;
 /** Max serialized bytes for a single envelope. */
@@ -389,7 +394,7 @@ export async function syncRoomFromPeer(basePath, peer, roomId, fetchImpl = fetch
  */
 export function serveFederation(basePath, opts = {}) {
     const host = opts.bindHost ?? '127.0.0.1';
-    const server = createServer((req, res) => {
+    const server = loadHttp().createServer((req, res) => {
         const send = (code, obj) => {
             const buf = Buffer.from(JSON.stringify(obj));
             res.writeHead(code, { 'content-type': 'application/json', 'content-length': buf.length });