🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(mods): doctor reports which claude runs, mods-by-default from 2.1.287, stale/mixed installs (ADR-404)
ruvc84c559189b3
diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.tsindex 2639567183..d88295c2ba 100644--- a/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts+++ b/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts@@ -10,6 +10,7 @@ import { join } from 'node:path';import { installMod, uninstallMod, withModEnabled, withModRemoved, ENABLE_ENV, MOD_PLUGIN_ID } from '../../src/mods/install.js';import { projectionOf, syncPolicyProjection, PROJECTION_RELATIVE } from '../../src/mods/policy-projection.js';import { probeMods } from '../../src/mods/probe.js';+import { findClaudeInstalls, judgeInstalls, versionLess } from '../../src/mods/claude-installs.js';import { modsCommand } from '../../src/commands/mods.js';import { setPolicyMode, upsertPolicyRule } from '../../src/services/policy-runtime.js';import { parseProjection } from '../../../../../plugins/ruflo-mods/hooks/guard/policy';@@ -26,7 +27,7 @@ afterEach(() => {});const read = (p: string) => JSON.parse(readFileSync(p, 'utf8'));const finding = (name: string, env: NodeJS.ProcessEnv = {}, managedPath = join(home, 'none.json')) =>- probeMods({ projectRoot: root, home, env, managedPath }).find((f) => f.name === name)!;+ probeMods({ projectRoot: root, home, env, managedPath, installs: [] }).find((f) => f.name === name)!;describe('ADR-404 mods install / uninstall', () => {it('enables the plugin, the marketplace and the early-access switch in settings.local.json', () => {@@ -173,3 +174,44 @@ describe('ADR-404 mods probe and doctor', () => {expect(read(join(root, '.claude', 'settings.local.json'))).toEqual({});});});++describe('ADR-404 claude installs', () => {+ const at = (path: string, version: string | null) => ({ path, version });++ it('mods on by default from 2.1.287; the env var for 2.1.277..2.1.286; older predates mods', () => {+ expect(judgeInstalls([at('/home/u/.local/bin/claude', '2.1.287')], false)).toMatchObject({ status: 'pass' });+ expect(judgeInstalls([at('/c', '2.1.282')], false)).toMatchObject({ status: 'warn', message: expect.stringContaining('need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)') });+ expect(judgeInstalls([at('/c', '2.1.282')], true)).toMatchObject({ status: 'pass' });+ expect(judgeInstalls([at('/c', '2.1.107')], true)).toMatchObject({ status: 'warn', message: expect.stringContaining('predates mods') });+ expect(judgeInstalls([], false).status).toBe('warn');+ });++ it('flags a mixed install: a stale claude first on PATH, or beside the current one', () => {+ const shadowed = judgeInstalls([at('/usr/bin/claude', '2.1.107'), at('/home/u/.local/bin/claude', '2.1.287')], false);+ expect(shadowed.status).toBe('warn');+ expect(shadowed.message).toContain('predates mods');+ expect(shadowed.message).toContain('also installed: /home/u/.local/bin/claude (2.1.287)');+ const beside = judgeInstalls([at('/home/u/.local/bin/claude', '2.1.287'), at('/usr/bin/claude', '2.1.107')], false);+ expect(beside).toMatchObject({ status: 'warn', message: expect.stringContaining('a stale one can shadow') });+ });++ it('versionLess compares numerically', () => {+ expect(versionLess('2.1.107', '2.1.287')).toBe(true);+ expect(versionLess('2.1.287', '2.1.287')).toBe(false);+ expect(versionLess('2.10.0', '2.9.9')).toBe(false);+ });++ it('finds every claude on PATH in order, de-duplicated by real path', () => {+ const a = mkdtempSync(join(tmpdir(), 'ruflo-mods-path-a-'));+ const b = mkdtempSync(join(tmpdir(), 'ruflo-mods-path-b-'));+ try {+ writeFileSync(join(a, 'claude'), '');+ writeFileSync(join(b, 'claude'), '');+ const found = findClaudeInstalls({ PATH: [a, b, a].join(':') }, join(a, 'nohome'), (p) => (p.startsWith(a) ? '2.1.107' : '2.1.287'));+ expect(found).toEqual([at(join(a, 'claude'), '2.1.107'), at(join(b, 'claude'), '2.1.287')]);+ } finally {+ rmSync(a, { recursive: true, force: true });+ rmSync(b, { recursive: true, force: true });+ }+ });+});diff --git a/v3/@claude-flow/cli/src/mods/claude-installs.ts b/v3/@claude-flow/cli/src/mods/claude-installs.tsnew file mode 100644index 0000000000..3523d805e9--- /dev/null+++ b/v3/@claude-flow/cli/src/mods/claude-installs.ts@@ -0,0 +1,94 @@+/**+ * Which Claude Code binaries a shell would find, and whether the one it runs+ * can load mods (ADR-404). Mods are on by default from Claude Code 2.1.287;+ * from 2.1.277 they load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1; older+ * builds predate them. A server-side rollout switch can still hold them off+ * on any version (reported separately). A stale install earlier on PATH+ * (a 2.1.107 npm-global beside a current native one, say) silently decides.+ */++import { execFileSync } from 'node:child_process';+import { existsSync, realpathSync, statSync } from 'node:fs';+import { delimiter, join } from 'node:path';++export const MODS_DEFAULT_ON = '2.1.287';+export const MODS_FIRST = '2.1.277';++export interface ClaudeInstall {+ path: string;+ version: string | null;+}++export type VersionOf = (path: string) => string | null;++const parse = (v: string) => v.split('.').map((n) => Number(n));+/** a < b for dotted numeric versions. */+export function versionLess(a: string, b: string): boolean {+ const x = parse(a);+ const y = parse(b);+ for (let i = 0; i < Math.max(x.length, y.length); i++) {+ if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);+ }+ return false;+}++/** `claude --version` of one binary, bounded; null when it cannot say. */+export const defaultVersionOf: VersionOf = (path) => {+ try {+ const out = execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });+ return out.match(/\d+\.\d+\.\d+/)?.[0] ?? null;+ } catch {+ return null;+ }+};++/** Every `claude` on PATH, in PATH order (the first is what runs), plus ~/.local/bin. */+export function findClaudeInstalls(env: NodeJS.ProcessEnv, home: string, versionOf: VersionOf = defaultVersionOf): ClaudeInstall[] {+ const names = process.platform === 'win32' ? ['claude.exe', 'claude.cmd', 'claude'] : ['claude'];+ const dirs = [...(env.PATH ?? '').split(delimiter).filter(Boolean), join(home, '.local', 'bin')];+ const seen = new Set<string>();+ const installs: ClaudeInstall[] = [];+ for (const dir of dirs) {+ for (const name of names) {+ const path = join(dir, name);+ let real: string;+ try {+ if (!existsSync(path) || !statSync(path).isFile()) continue;+ real = realpathSync(path);+ } catch {+ continue;+ }+ if (seen.has(real)) continue;+ seen.add(real);+ installs.push({ path, version: versionOf(path) });+ }+ }+ return installs;+}++export interface InstallsFinding {+ status: 'pass' | 'warn';+ message: string;+ fix?: string;+}++/** The doctor's reading of what `claude` resolves to and what else is installed. */+export function judgeInstalls(installs: readonly ClaudeInstall[], enableEnvSet: boolean): InstallsFinding {+ if (installs.length === 0) return { status: 'warn', message: 'no claude binary on PATH', fix: 'install Claude Code >= 2.1.287' };+ const [first] = installs;+ const others = installs.slice(1).filter((i) => i.version !== first!.version);+ const mixed = others.length+ ? `; also installed: ${others.map((i) => `${i.path} (${i.version ?? 'unknown'})`).join(', ')}. The first on PATH runs; a stale one can shadow a current one.`+ : '';+ const runs = `${first!.path} (${first!.version ?? 'version unknown'})`;+ if (!first!.version) return { status: 'warn', message: `claude resolves to ${runs}${mixed}` };+ if (!versionLess(first!.version, MODS_DEFAULT_ON)) {+ return { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods on by default${mixed}` };+ }+ if (!versionLess(first!.version, MODS_FIRST)) {+ return enableEnvSet+ ? { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}` }+ : { status: 'warn', message: `claude resolves to ${runs}: below ${MODS_DEFAULT_ON}, mods need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON}, or export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` };+ }+ return { status: 'warn', message: `claude resolves to ${runs}: predates mods (< ${MODS_FIRST}); classic hooks handle every event${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON} and remove the stale install from PATH` };+}diff --git a/v3/@claude-flow/cli/src/mods/probe.ts b/v3/@claude-flow/cli/src/mods/probe.tsindex 841b1a6b05..dc1da5305e 100644--- a/v3/@claude-flow/cli/src/mods/probe.ts+++ b/v3/@claude-flow/cli/src/mods/probe.ts@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from 'node:fs';import { homedir, platform } from 'node:os';import { join, resolve } from 'node:path';+import { findClaudeInstalls, judgeInstalls, type ClaudeInstall } from './claude-installs.js';import { ENABLE_ENV, MOD_PLUGIN_ID, readRecord, readSettingsFile, settingsFileFor } from './install.js';import { PROJECTION_RELATIVE } from './policy-projection.js';@@ -48,6 +49,8 @@ export interface ProbeInputs {home?: string;env?: NodeJS.ProcessEnv;managedPath?: string;+ /** Claude Code binaries on PATH; discovered (each `--version` run) when absent. */+ installs?: ClaudeInstall[];}export function probeMods(inputs: ProbeInputs): Finding[] {@@ -78,6 +81,9 @@ export function probeMods(inputs: ProbeInputs): Finding[] {return false;}});++ // 2a. Which Claude Code runs, and whether a stale install shadows it.+ findings.push({ name: 'claude installs', ...judgeInstalls(inputs.installs ?? findClaudeInstalls(env, home), envOn || settingsOn) });// Observed on Claude Code 2.1.282 (ADR-404): the server-side rollout switch// decides. Served on, an installed mod loaded with ENABLE_ENV unset; served// off, it did not load with ENABLE_ENV=1. The variable is reported, never