π 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
fix(console): CLI launcher resolution and cold-start handling for settings writes (fixes #3914)
ruv56a638190d2a
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.jsonindex 5ff336bc56..6fb4bbb567 100644--- a/plugins/ruflo-console/.claude-plugin/plugin.json+++ b/plugins/ruflo-console/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-console","description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings β Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",- "version": "0.40.0",+ "version": "0.40.1","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-console/CHANGELOG.md b/plugins/ruflo-console/CHANGELOG.mdindex d72fbabb3a..0c300341f9 100644--- a/plugins/ruflo-console/CHANGELOG.md+++ b/plugins/ruflo-console/CHANGELOG.md@@ -2,6 +2,10 @@Newest first. One `## <version> β <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-console`.+## 0.40.1 β 2026-10-08+- fix: a settings write (or any confirmed ruflo CLI action) no longer aborts with "still running after 90000ms" when the CLI is not in the npm cache (#3914): with the ruflo CLI option on npx it now uses ruflo on PATH, a project-local bin, or the cached npx copy first, and only then a cold download, which gets a 5 minute limit and says "first run downloads the ruflo CLI"+- fix: a timeout or an uncached npx now ends as an error that names the fix (npm i -g ruflo, or npx -y @claude-flow/cli@latest --version once), and a retry after the cache is warm runs at once+## 0.40.0 β 2026-10-08- feat: advisor checkpoints for mission loops (ADR-483), off by default (Settings β Advisor checkpoints): a read-only second opinion before a plan locks, when the same check fails twice in a row, and before a mission is declared done; a third failure in a row pauses the mission- feat: each consult is a separate claude -p turn in plan mode on the model you choose (Settings β Advisor model), asked first with the exact command, under the turn budget and the mission spend cap; it is not Claude Codeβs in-session advisor, which a mod cannot calldiff --git a/plugins/ruflo-console/hooks/launcher.ts b/plugins/ruflo-console/hooks/launcher.tsnew file mode 100644index 0000000000..e8e1569bf8--- /dev/null+++ b/plugins/ruflo-console/hooks/launcher.ts@@ -0,0 +1,90 @@+/**+ * Which command reaches the ruflo CLI for a confirmed action (ADR-407 update, ADR-444). With the `cli` option on `npx` the+ * argv used to be `npx -y @claude-flow/cli@latest ...` with a 90 s limit, so in a project whose npm cache lacked the package+ * a settings write downloaded about 2.5 GB, was killed at 90 s and showed "still running after 90000ms". The launcher is now+ * chosen once, cheapest first: `ruflo` on PATH, a project-local bin, the cached npx copy, and only then a cold download, which+ * gets a long limit and says it is a first run. The other `cli` choices are the person's explicit pick and are never changed.+ */+import type { Host } from './host'+import { CLI_PREFIXES, type State } from './state'++export type LauncherKind = 'fixed' | 'path' | 'local' | 'cached' | 'cold'+export type Launcher = { prefix: readonly string[]; kind: LauncherKind }++/** A cold `npx -y @claude-flow/cli@latest` took 36 s on a fast link (2.5 GB cache); five minutes covers a slow one. */+export const COLD_TIMEOUT_MS = 300_000+export const FIRST_RUN_LABEL = 'first run downloads the ruflo CLI: this can take a few minutes'+const PROBE_MS = 5_000+const CACHED_PROBE_MS = 20_000++/** Tried in order; the first whose `--version` answers wins. Relative paths run in the project (the host's cwd). */+const CANDIDATES: readonly { kind: LauncherKind; prefix: readonly string[]; timeoutMs: number }[] = [+ { kind: 'path', prefix: ['ruflo'], timeoutMs: PROBE_MS },+ { kind: 'local', prefix: ['node_modules/.bin/ruflo'], timeoutMs: PROBE_MS },+ { kind: 'local', prefix: ['node_modules/.bin/claude-flow'], timeoutMs: PROBE_MS },+ { kind: 'cached', prefix: CLI_PREFIXES['npx-offline'], timeoutMs: CACHED_PROBE_MS },+]++// A found launcher is kept for the session (per cli choice); a cold answer never is, since the first run warms the cache.+const found = new WeakMap<State, { cli: string; launcher: Launcher }>()++async function answers(host: Host, prefix: readonly string[], timeoutMs: number): Promise<boolean> {+ try {+ const result = await host.run([...prefix, '--version'], timeoutMs)++ return result.exitCode === 0 && result.stdout.trim() !== ''+ } catch {+ return false+ }+}++export async function resolveLauncher(host: Host, state: State): Promise<Launcher> {+ const cli = state.options.cli++ if (cli !== 'npx') return { prefix: CLI_PREFIXES[cli], kind: 'fixed' }++ const kept = found.get(state)++ if (kept !== undefined && kept.cli === cli) return kept.launcher++ for (const candidate of CANDIDATES) {+ if (await answers(host, candidate.prefix, candidate.timeoutMs)) {+ const launcher = { prefix: candidate.prefix, kind: candidate.kind }++ found.set(state, { cli, launcher })++ return launcher+ }+ }++ return { prefix: CLI_PREFIXES.npx, kind: 'cold' }+}++/** Forgets the kept launcher: a failed run may mean the cache or the install changed. */+export function forgetLauncher(state: State): void {+ found.delete(state)+}++const WARM = 'npx -y @claude-flow/cli@latest --version'++/** What to tell the person when a run of the CLI could not finish, or null when the failure is not about reaching the CLI. */+export function explainFailure(argv: readonly string[], failure: { error?: unknown; exitCode?: number; stdout?: string; stderr?: string }): string | null {+ if (argv[0] !== 'npx') return null++ const isOffline = argv.includes('--offline')++ if (failure.error !== undefined) {+ const message = failure.error instanceof Error ? failure.error.message : String(failure.error)+ const ms = /still running after (\d+)\s*ms/.exec(message)?.[1]++ if (ms === undefined && !/aborted|timed out/i.test(message)) return null++ return `npx did not finish${ms === undefined ? '' : ` in ${Math.round(Number(ms) / 1000)} s`}: it was likely still downloading the ruflo CLI. Install it once with "npm i -g ruflo" or warm the cache with "${WARM}", then ask again`+ }++ if (isOffline && failure.exitCode !== 0 && /\bENOTCACHED\b/.test(`${failure.stderr ?? ''}\n${failure.stdout ?? ''}`)) {+ return `the ruflo CLI is not cached here. Run "${WARM}" once (or "npm i -g ruflo"), or set the ruflo CLI option to npx, then ask again`+ }++ return null+}diff --git a/plugins/ruflo-console/hooks/runner.ts b/plugins/ruflo-console/hooks/runner.tsindex ca8d5b5ece..f8123e67d6 100644--- a/plugins/ruflo-console/hooks/runner.ts+++ b/plugins/ruflo-console/hooks/runner.ts@@ -13,7 +13,8 @@ import type { Host } from './host'import { labLines } from './mh-lab'import { outputLines } from './ops'import { filterPalette, paletteEntries, textOfQuery, type PaletteEntry } from './palette'-import { CLI_PREFIXES, type State } from './state'+import { COLD_TIMEOUT_MS, explainFailure, FIRST_RUN_LABEL, forgetLauncher, resolveLauncher } from './launcher'+import type { State } from './state'import { prettyLines } from './result-lines'export const PENDING_TTL_MS = 30_000@@ -65,12 +66,24 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runner// The x.ruv.io board keeps its own result panel, so its runs never show in the MetaHarness lab.const panel = spec.board === 'xruv' ? state.xruv : state.lab+ let lastArgv: readonly string[] = spec.argv ?? []+state.isActing = trueif (spec.lab !== undefined) panel.running = { id: spec.lab, label: spec.label, startedAtMs: Date.now() }host.invalidate()try {- const result = await host.run(spec.argv ?? [...CLI_PREFIXES[state.options.cli], ...spec.args], spec.timeoutMs ?? 90_000, spec.stdin)+ // A CLI action picks its launcher once per session; a cold npx download gets a long limit and says it is a first run.+ const launcher = spec.argv === undefined ? await resolveLauncher(host, state) : null+ const argv = spec.argv ?? [...(launcher?.prefix ?? []), ...spec.args]+ const isCold = launcher?.kind === 'cold'++ lastArgv = argv++ if (isCold) say(spec.label, true, FIRST_RUN_LABEL)+ const result = await host.run(argv, isCold ? Math.max(spec.timeoutMs ?? 0, COLD_TIMEOUT_MS) : spec.timeoutMs ?? 90_000, spec.stdin)++ if (result.exitCode !== 0) forgetLauncher(state)const answer = /"success"\s*:\s*(true|false)/.exec(result.stdout)?.[1]const error = /"error"\s*:\s*"([^"]{0,160})"/.exec(result.stdout)?.[1] ?? /\[ERROR\]\s*(.{0,160})/.exec(result.stdout)?.[1]// `mcp exec` wraps a tool's failure as `"isError": true` with its message escaped inside: that is a failure too.@@ -85,7 +98,7 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runnerif (result.exitCode === 0) spec.onOutput?.(result.stdout)if (spec.isReadOnly === true) {- say(spec.label, ok, ok ? 'the ruflo CLI answered:' : plain(error ?? result.stderr, 160) || `exit ${result.exitCode}`, spec.lab === undefined ? outputLines(result.stdout) : undefined)+ say(spec.label, ok, ok ? 'the ruflo CLI answered:' : explainFailure(argv, result) ?? (plain(error ?? result.stderr, 160) || `exit ${result.exitCode}`), spec.lab === undefined ? outputLines(result.stdout) : undefined)return}@@ -100,11 +113,13 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runnerlabel: spec.label,ok: ok && verified !== 'no',verified,- detail: ok ? `${spec.argv === undefined ? 'ruflo' : 'the command'} answered ok; expected ${spec.expect}` : plain(error ?? result.stderr, 160) || `exit ${result.exitCode}`,+ detail: ok ? `${spec.argv === undefined ? 'ruflo' : 'the command'} answered ok; expected ${spec.expect}` : explainFailure(argv, result) ?? (plain(error ?? result.stderr, 160) || `exit ${result.exitCode}`),atMs: Date.now(),}} catch (error) {- const why = plain(error instanceof Error ? error.message : String(error), 160) || 'refused'+ forgetLauncher(state)++ const why = explainFailure(lastArgv, { error }) ?? (plain(error instanceof Error ? error.message : String(error), 160) || 'refused')if (spec.lab !== undefined) panel.result = { id: spec.lab, label: spec.label, ok: false, exitCode: null, ...(spec.note !== undefined && { note: spec.note }), lines: [why], atMs: Date.now() }say(spec.label, false, why)diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.tsindex b72ed45b86..beea741f8a 100644--- a/plugins/ruflo-console/hooks/version.ts+++ b/plugins/ruflo-console/hooks/version.ts@@ -2,4 +2,4 @@* The console's version, shown on the header so a person can tell which build is running. Kept equal to the plugin's manifest* (`.claude-plugin/plugin.json`); tests/version.spec.ts fails if the two drift.*/-export const CONSOLE_VERSION = '0.40.0'+export const CONSOLE_VERSION = '0.40.1'diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.shindex c72acc45df..a82908d3a8 100755--- a/plugins/ruflo-console/scripts/smoke.sh+++ b/plugins/ruflo-console/scripts/smoke.sh@@ -11,9 +11,9 @@ step() { printf "β %s ... " "$1"; }ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }-step "1. plugin.json declares ruflo-console 0.40.0"+step "1. plugin.json declares ruflo-console 0.40.1"grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \- && grep -q '"version": "0.40.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"+ && grep -q '"version": "0.40.1"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"step "2. hooks.json names exactly one module and no classic hook commands"grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \diff --git a/plugins/ruflo-console/tests/launcher.spec.ts b/plugins/ruflo-console/tests/launcher.spec.tsnew file mode 100644index 0000000000..19eab51825--- /dev/null+++ b/plugins/ruflo-console/tests/launcher.spec.ts@@ -0,0 +1,159 @@+/**+ * The CLI launcher for confirmed actions (ADR-407 update): a settings write in a project whose npm cache lacks @claude-flow/cli+ * used to run `npx -y @claude-flow/cli@latest ...` with a 90 s limit and fail with "still running after 90000ms".+ * npx vitest run plugins/ruflo-console/tests/launcher.spec.ts+ */+import { describe, expect, it } from 'vitest'++import type { ActionSpec } from '../hooks/actions'+import type { Host } from '../hooks/host'+import { explainFailure, FIRST_RUN_LABEL } from '../hooks/launcher'+import { createRunner } from '../hooks/runner'+import { setCore } from '../hooks/settings'+import { newState, type CliChoice } from '../hooks/state'++type Answer = { exitCode: number; stdout: string; stderr: string } | Error+type Call = { argv: readonly string[]; timeoutMs: number }++const ok = (stdout = '1.0.0'): Answer => ({ exitCode: 0, stdout, stderr: '' })+const key = (argv: readonly string[]): string => argv.join(' ')++/** A host whose process runner answers from `script` by argv (an Error rejects, as a missing binary or a kill does). */+function world(cli: CliChoice, script: (argv: readonly string[]) => Answer) {+ const calls: Call[] = []+ const state = newState({})+ const seen: string[] = []+ const host = {+ invalidate: () => seen.push(state.outcome?.detail ?? ''),+ after: () => ({ cancel: () => undefined }),+ run: async (argv: readonly string[], timeoutMs: number) => {+ calls.push({ argv, timeoutMs })+ const answer = script(argv)++ if (answer instanceof Error) throw answer++ return answer+ },+ } as unknown as Host++ state.options.cli = cli++ const runner = createRunner(state, host, { freshRead: async () => undefined, setView: () => undefined, drill: () => undefined, command: () => undefined })+ const write = (): ActionSpec => setCore(state, 'swarm.maxAgents', '15', () => undefined) as ActionSpec+ const confirmWrite = async () => {+ runner.ask(write(), 'why not')+ await runner.confirm()+ }+ const writeCall = () => calls.filter(call => call.argv.includes('set'))++ return { state, calls, seen, runner, confirmWrite, writeCall }+}++const missing = () => Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' })+const NEVER_CACHED: Answer = { exitCode: 1, stdout: '', stderr: 'npm error code ENOTCACHED\nnpm error cache mode is only-if-cached' }++describe('the write picks the cheapest launcher that answers (cli = npx)', () => {+ it('uses ruflo on PATH, with the ordinary 90 s limit', async () => {+ const w = world('npx', argv => (key(argv) === 'ruflo --version' || argv[0] === 'ruflo' ? ok() : missing()))++ await w.confirmWrite()+ expect(w.writeCall()).toEqual([{ argv: ['ruflo', 'config', 'set', '-k', 'swarm.maxAgents', '-v', '15'], timeoutMs: 90_000 }])+ expect(w.state.outcome?.ok).toBe(true)+ })++ it('falls through a missing ruflo to the project-local bin', async () => {+ const w = world('npx', argv => (argv[0] === 'node_modules/.bin/ruflo' ? ok() : missing()))++ await w.confirmWrite()+ expect(w.writeCall()[0]?.argv.slice(0, 2)).toEqual(['node_modules/.bin/ruflo', 'config'])+ })++ it('falls through to the cached npx copy and never to the online one', async () => {+ const w = world('npx', argv => (argv[0] === 'npx' && argv.includes('--offline') ? ok() : missing()))++ await w.confirmWrite()+ expect(w.writeCall()[0]?.argv.slice(0, 4)).toEqual(['npx', '--offline', '-y', '@claude-flow/cli@latest'])+ expect(w.writeCall()[0]?.timeoutMs).toBe(90_000)+ })++ it('keeps the launcher it found: a second write does not probe again', async () => {+ const w = world('npx', argv => (argv[0] === 'ruflo' ? ok() : missing()))++ await w.confirmWrite()+ const probes = w.calls.length+ await w.confirmWrite()+ expect(w.calls.length).toBe(probes + 1)+ })+})++describe('a cold download is the last resort and is announced', () => {+ const cold = (argv: readonly string[]): Answer => (key(argv).includes('--version') ? missing() : ok('Set swarm.maxAgents = 15'))++ it('runs online npx with the long limit and shows the first-run label while it works', async () => {+ const w = world('npx', cold)++ await w.confirmWrite()+ expect(w.writeCall()).toEqual([{ argv: ['npx', '-y', '@claude-flow/cli@latest', 'config', 'set', '-k', 'swarm.maxAgents', '-v', '15'], timeoutMs: 300_000 }])+ expect(w.seen).toContain(FIRST_RUN_LABEL)+ expect(w.state.outcome?.ok).toBe(true)+ expect(w.state.isActing).toBe(false)+ })++ it('ends a timeout as an error that names the exact fix, not the raw abort, and is not stuck', async () => {+ const w = world('npx', argv => (key(argv).includes('--version') ? missing() : new Error('ruflo-console: $.process.run(npx) aborted: still running after 300000ms')))++ await w.confirmWrite()+ expect(w.state.outcome?.ok).toBe(false)+ expect(w.state.outcome?.detail).toContain('npm i -g ruflo')+ expect(w.state.outcome?.detail).toContain('npx -y @claude-flow/cli@latest --version')+ expect(w.state.outcome?.detail).not.toContain('still running after')+ expect(w.state.isActing).toBe(false)+ })++ it('a retry after the cache is warm is fast: it resolves to the cached copy', async () => {+ let warm = false+ const w = world('npx', argv => {+ if (argv[0] === 'npx' && argv.includes('--offline')) return warm ? ok() : NEVER_CACHED+ if (key(argv).includes('--version')) return missing()++ return warm ? ok('Set') : new Error('aborted: still running after 300000ms')+ })++ await w.confirmWrite()+ expect(w.state.outcome?.ok).toBe(false)+ warm = true+ await w.confirmWrite()+ expect(w.state.outcome?.ok).toBe(true)+ expect(w.writeCall().at(-1)).toEqual({ argv: ['npx', '--offline', '-y', '@claude-flow/cli@latest', 'config', 'set', '-k', 'swarm.maxAgents', '-v', '15'], timeoutMs: 90_000 })+ })+})++describe('the explicit cli choices are never changed', () => {+ it('npx-offline runs as chosen, with no probes, and turns ENOTCACHED into the fix', async () => {+ const w = world('npx-offline', () => NEVER_CACHED)++ await w.confirmWrite()+ expect(w.calls.map(call => call.argv.slice(0, 3))).toEqual([['npx', '--offline', '-y']])+ expect(w.state.outcome?.ok).toBe(false)+ expect(w.state.outcome?.detail).toContain('not cached')+ expect(w.state.outcome?.detail).toContain('npx -y @claude-flow/cli@latest --version')+ })++ it('ruflo runs as chosen, with no probes', async () => {+ const w = world('ruflo', () => ok('Set'))++ await w.confirmWrite()+ expect(w.calls.map(call => call.argv[0])).toEqual(['ruflo'])+ })+})++describe('explainFailure', () => {+ it('speaks only about npx', () => {+ expect(explainFailure(['ruflo', 'x'], { error: new Error('aborted: still running after 90000ms') })).toBeNull()+ expect(explainFailure(['npx', '-y', 'x'], { exitCode: 1, stderr: 'boom' })).toBeNull()+ })++ it('names the seconds of a timeout', () => {+ expect(explainFailure(['npx', '-y', 'x'], { error: new Error('$.process.run(npx) aborted: still running after 90000ms') })).toContain('in 90 s')+ })+})diff --git a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md b/v3/docs/adr/ADR-407-ruflo-console-cockpit.mdindex 3917b7cc8b..718063915d 100644--- a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md+++ b/v3/docs/adr/ADR-407-ruflo-console-cockpit.md@@ -265,3 +265,19 @@ levels (simple or advanced), "changed only", "read again" and the search box areWith search text the page is a flat list grouped by source (`ββ UI`, `ββ ruflo-console`, and so on), not sections, so the order above doesnot apply and any setting is found in either level. `hooks/settings-palette.ts` lists headless commands (`settings-set` and the like), notsections; it needs no change and has none.++## Update 2026-10-08: how a confirmed action reaches the ruflo CLI (0.40.1, #3914)++Β§8 says every change runs as one fixed argv. The prefix of that argv comes from the ruflo CLI option (`CLI_PREFIXES`: `npx-offline` (default),+`npx`, `ruflo`, `claude-flow`), and the runner's limit for an action without its own `timeoutMs` is 90 s. With `npx` in a project whose+npm cache lacked `@claude-flow/cli`, a settings write started a cold download (about 2.5 GB; 36 s on a fast link, longer on a slow or loaded+one), was aborted at 90 s and showed the raw "still running after 90000ms". Now (`hooks/launcher.ts`, used by `hooks/runner.ts`):++- The explicit choices `npx-offline`, `ruflo` and `claude-flow` run exactly as chosen. Only `npx` (the person allowed the network) resolves a+ launcher once per session, cheapest first: `ruflo` on PATH, `node_modules/.bin/ruflo`, `node_modules/.bin/claude-flow`, the cached+ `npx --offline` copy (each probed with `--version`), and last the online `npx`, called a cold run.+- A cold run gets a 300 s limit and the outcome line reads "first run downloads the ruflo CLI: this can take a few minutes". It is not kept:+ the next write re-resolves, finds the warmed cache and runs at the ordinary limit.+- A timeout, or `ENOTCACHED` from `npx --offline`, ends the action as an error naming the fix: `npm i -g ruflo`, or+ `npx -y @claude-flow/cli@latest --version` once. Read probes keep their own limits and the existing "ruflo CLI not cached" hint.+- Reads and other callers that build `[...CLI_PREFIXES[cli], ...]` themselves (drill logs, the terminal harness, mission specs) are unchanged.