claude-flow 3.56.9 → 3.56.10

package/v3/@claude-flow/cli/dist/src/commands/daemon.js

@@ -164,37 +164,44 @@ const startCommand = {
                 fs.mkdirSync(stateDir, { recursive: true });
             }
             catch { /* exists */ }
-            try {
-                lockFd = fs.openSync(lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
-                fs.writeSync(lockFd, String(process.pid));
-            }
-            catch (e) {
-                if (e.code === 'EEXIST') {
-                    // Another `daemon start` is mid-spawn. Wait up to 5s for it to
-                    // finish, then re-check the PID file. If the holder crashed
-                    // mid-spawn, fall through and reset; killStaleDaemons + a fresh
-                    // attempt will recover.
-                    const deadline = Date.now() + 5000;
-                    while (Date.now() < deadline) {
-                        await new Promise((r) => setTimeout(r, 100));
-                        const winnerPid = getBackgroundDaemonPid(projectRoot);
-                        if (winnerPid && isProcessRunning(winnerPid)) {
-                            if (!quiet) {
-                                output.printWarning(`Daemon already running in background (PID: ${winnerPid}). Stop it first with: daemon stop`);
-                            }
-                            return { success: true };
+            lockFd = tryAcquireDaemonLock(lockFile);
+            if (lockFd === null) {
+                // Another `daemon start` is mid-spawn. Wait for it while its holder
+                // is alive; only a lock whose holder is DEAD is stale and may be
+                // retaken — atomically, via O_EXCL again, never by proceeding
+                // lockless. The old fixed 5s timeout + unlink let every waiter
+                // through on Windows, where the holder's killStaleDaemons
+                // (`tasklist /v`) routinely takes longer than that, and each waiter
+                // then forked its own daemon (3 per workspace observed).
+                const waitMs = Number(process.env.RUFLO_DAEMON_LOCK_WAIT_MS) > 0
+                    ? Number(process.env.RUFLO_DAEMON_LOCK_WAIT_MS)
+                    : 60_000;
+                const deadline = Date.now() + waitMs;
+                while (lockFd === null) {
+                    const winnerPid = getBackgroundDaemonPid(projectRoot);
+                    if (winnerPid && isProcessRunning(winnerPid)) {
+                        if (!quiet) {
+                            output.printWarning(`Daemon already running in background (PID: ${winnerPid}). Stop it first with: daemon stop`);
                         }
+                        return { success: true };
                     }
-                    // Stale lockfile from a crashed prior attempt — clear it and
-                    // proceed without a held lock. Worst case we double-spawn ONCE
-                    // and the killStaleDaemons sweep below cleans up.
-                    try {
-                        fs.unlinkSync(lockFile);
+                    if (daemonLockIsStale(lockFile)) {
+                        try {
+                            fs.unlinkSync(lockFile);
+                        }
+                        catch { /* raced with another taker */ }
+                        lockFd = tryAcquireDaemonLock(lockFile);
+                        continue;
                     }
-                    catch { /* ignore */ }
-                }
-                else {
-                    throw e;
+                    if (Date.now() >= deadline) {
+                        // A live process is still starting the daemon. Spawning another
+                        // would be the duplicate this lock exists to prevent.
+                        if (!quiet) {
+                            output.printWarning('Another `daemon start` is still in progress for this workspace; not starting a second daemon.');
+                        }
+                        return { success: true };
+                    }
+                    await new Promise((r) => setTimeout(r, 100));
                 }
             }
             // Dedup check while holding the lock.
@@ -298,15 +305,22 @@ const startCommand = {
             // NOTE: Do NOT write PID file here — startDaemon() writes it internally.
             // Writing it before startDaemon() causes checkExistingDaemon() to detect
             // our own PID and return early, leaving no workers scheduled (#1478 Bug 1).
-            // Clean up PID file on exit
+            // Clean up PID file on exit — only if it is OURS. A process that lost
+            // the singleton race must never delete the winner's PID file, or the
+            // next auto-start sees "no daemon" and forks yet another one.
             const cleanup = () => {
                 try {
-                    if (fs.existsSync(pidFile)) {
+                    if (fs.existsSync(pidFile) && fs.readFileSync(pidFile, 'utf-8').trim() === String(process.pid)) {
                         fs.unlinkSync(pidFile);
                     }
                 }
                 catch { /* ignore */ }
             };
+            // WorkerDaemon.start() declines (returns without running) when another
+            // live daemon already owns daemon.pid. Such a process must exit rather
+            // than park on the keep-alive below: it has no workers and no TTL, so
+            // it would linger as an idle duplicate forever.
+            const declined = (d) => !d.getStatus().running;
             process.on('exit', cleanup);
             process.on('SIGINT', () => { cleanup(); process.exit(0); });
             process.on('SIGTERM', () => { cleanup(); process.exit(0); });
@@ -319,6 +333,11 @@ const startCommand = {
                 spinner.start();
                 const daemon = await startDaemon(projectRoot, config);
                 const status = daemon.getStatus();
+                if (declined(daemon)) {
+                    spinner.stop();
+                    output.printWarning(`Daemon already running (PID: ${getBackgroundDaemonPid(projectRoot) ?? 'unknown'}); not starting a second one.`);
+                    return { success: true };
+                }
                 spinner.succeed('Worker daemon started (foreground mode)');
                 output.writeln();
                 output.printBox([
@@ -371,7 +390,9 @@ const startCommand = {
                 await new Promise(() => { }); // Never resolves - daemon runs until killed
             }
             else {
-                await startDaemon(projectRoot, config);
+                const daemon = await startDaemon(projectRoot, config);
+                if (declined(daemon))
+                    return { success: true };
                 setInterval(() => { }, 60_000); // Keep alive with ref'd handle (#1478)
                 await new Promise(() => { }); // Keep alive
             }
@@ -910,6 +931,40 @@ function getBackgroundDaemonPid(projectRoot) {
         return null;
     }
 }
+/**
+ * Atomically create the launcher lock and stamp it with our PID.
+ * Returns the fd, or null when another process holds the lock.
+ */
+function tryAcquireDaemonLock(lockFile) {
+    try {
+        const fd = fs.openSync(lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+        fs.writeSync(fd, String(process.pid));
+        return fd;
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return null;
+        throw e;
+    }
+}
+/**
+ * A lock is stale only when its holder is gone. An empty lock is the brief
+ * window between O_EXCL create and the PID write, so it counts as held
+ * unless it has been empty for a while (holder crashed in that window).
+ */
+function daemonLockIsStale(lockFile) {
+    try {
+        const raw = fs.readFileSync(lockFile, 'utf-8').trim();
+        const pid = parseInt(raw, 10);
+        if (!raw || Number.isNaN(pid)) {
+            return Date.now() - fs.statSync(lockFile).mtimeMs > 10_000;
+        }
+        return pid !== process.pid && !isProcessRunning(pid);
+    }
+    catch {
+        return false; // vanished: the next O_EXCL attempt decides
+    }
+}
 /**
  * Check if a process is running
  */

package/v3/@claude-flow/cli/dist/src/commands/memory.js

@@ -3,6 +3,7 @@
  * Memory operations for AgentDB integration
  */
 import { validateAppendConditions } from '../memory/append-conditions.js';
+import { DEFAULT_SEARCH_THRESHOLD, nearMisses } from '../memory/search-defaults.js';
 import { output } from '../output.js';
 import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
@@ -430,7 +431,7 @@ const searchCommand = {
             // default to 0.7, which silently re-broke #2558: `memory search` matched
             // content word-for-word and still returned nothing. Regression guard:
             // __tests__/memory-search-recall-2558.test.ts.
-            default: 0.3
+            default: 0.2
         },
         {
             name: 'type',
@@ -499,7 +500,9 @@ const searchCommand = {
         // coalescing preserves an explicit zero. Fallback aligned with the
         // option's declared `default: 0.7` (was `0.3` — the two disagreed
         // and --help advertised a default the code did not honor).
-        const threshold = ctx.flags.threshold ?? 0.3;
+        const threshold = ctx.flags.threshold ?? DEFAULT_SEARCH_THRESHOLD;
+        // The parser fills the option's declared default, so an untouched flag arrives as the default value.
+        const thresholdWasDefault = ctx.flags.threshold === undefined || ctx.flags.threshold === DEFAULT_SEARCH_THRESHOLD;
         const searchType = ctx.flags.type || 'semantic';
         const buildHnsw = (ctx.flags['build-hnsw'] || ctx.flags.buildHnsw);
         const requestedIntent = ctx.flags.intent || 'mixed';
@@ -738,6 +741,15 @@ const searchCommand = {
             output.writeln();
             if (results.length === 0) {
                 output.printWarning('No results found');
+                if (thresholdWasDefault) {
+                    const near = await nearMisses(searchEntries, { query, namespace, provenanceFilter, dbPath: dbPathSearch });
+                    if (near) {
+                        output.writeln(output.dim(`  ${near.hint.replace(' in nearMisses', ' below').replace('Pass threshold: 0', 'Pass --threshold 0')}`));
+                        for (const n of near.nearMisses) {
+                            output.writeln(output.dim(`    ${n.similarity.toFixed(2)}  ${n.namespace}/${n.key}`));
+                        }
+                    }
+                }
                 await warnIfSiblingHasRows(ctx.flags.path);
                 output.writeln(output.dim('Try: claude-flow memory store -k "key" --value "data"'));
                 return { success: true, data: [] };

package/v3/@claude-flow/cli/dist/src/commands/security-code-patterns.d.ts

@@ -6,8 +6,8 @@
  *  - every rule is tested after comment text is blanked, so a comment naming `child_process.execFile` or `eval(` is
  *    not a finding;
  *  - eval needs a word start: "retrieval (" in prose is not a call; `eval(` and `window.eval(` still are;
- *  - command injection keeps the old rule's reach (any `exec` after `child_process` on the line), and no longer skips
- *    execSync as `exec[^S]` did;
+ *  - command injection keeps the old rule's reach (any `exec` after `child_process` on the line), and also catches
+ *    dynamic exec/execSync command strings when the import was on another line;
  *  - a pg placeholder such as `$${paramCount + 1}` is a parameter number, not a value in the SQL text. It is exempt only
  *    when its expression is a number, a loop letter, `params.length`-style, or a name containing `param` or `placeholder`, it
  *    stands where SQL takes a value, and it is not inside a quoted SQL string.

package/v3/@claude-flow/cli/dist/src/commands/security-code-patterns.js

@@ -6,14 +6,72 @@
  *  - every rule is tested after comment text is blanked, so a comment naming `child_process.execFile` or `eval(` is
  *    not a finding;
  *  - eval needs a word start: "retrieval (" in prose is not a call; `eval(` and `window.eval(` still are;
- *  - command injection keeps the old rule's reach (any `exec` after `child_process` on the line), and no longer skips
- *    execSync as `exec[^S]` did;
+ *  - command injection keeps the old rule's reach (any `exec` after `child_process` on the line), and also catches
+ *    dynamic exec/execSync command strings when the import was on another line;
  *  - a pg placeholder such as `$${paramCount + 1}` is a parameter number, not a value in the SQL text. It is exempt only
  *    when its expression is a number, a loop letter, `params.length`-style, or a name containing `param` or `placeholder`, it
  *    stands where SQL takes a value, and it is not inside a quoted SQL string.
  */
 /** No `g` flag, so `test` keeps no lastIndex between lines. */
 const re = (pattern) => (line) => pattern.test(line);
+/** Detect a dynamic shell command at an exec/execSync call site, independent of its import. */
+const interpolatedExec = (line) => {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote !== null) {
+            if (ch === '\\') {
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        if (i > 0 && /[\w$]/.test(line[i - 1]))
+            continue;
+        const name = line.startsWith('execSync', i) ? 'execSync' : line.startsWith('exec', i) ? 'exec' : '';
+        if (!name)
+            continue;
+        let arg = i + name.length;
+        while (/\s/.test(line[arg] ?? ''))
+            arg++;
+        if (line[arg++] !== '(')
+            continue;
+        while (/\s/.test(line[arg] ?? ''))
+            arg++;
+        const delimiter = line[arg];
+        if (delimiter !== '`' && delimiter !== "'" && delimiter !== '"')
+            continue;
+        for (let end = arg + 1; end < line.length; end++) {
+            if (line[end] === '\\') {
+                end++;
+                continue;
+            }
+            if (delimiter === '`' && line[end] === '$' && line[end + 1] === '{')
+                return true;
+            if (line[end] !== delimiter)
+                continue;
+            if (delimiter !== '`') {
+                let next = end + 1;
+                while (/\s/.test(line[next] ?? ''))
+                    next++;
+                if (line[next++] === '+') {
+                    while (/\s/.test(line[next] ?? ''))
+                        next++;
+                    if (/[A-Za-z_$]/.test(line[next] ?? ''))
+                        return true;
+                }
+            }
+            break;
+        }
+    }
+    return false;
+};
 // A `.length` counts only on a param-, value- or arg-named array: `req.body.length` is whatever the client sent.
 const COUNTER = /^\s*(?:\d+|[ijkn]|(?:[A-Za-z_$][\w$]*(?:Params?|Placeholders?|Values?|Args?)|params?|placeholders?|values?|args?)\.length|[A-Za-z_$]*(?:[Pp]aram|[Pp]laceholder)[\w$]*)\s*(?:[+-]\s*\d+\s*)?$/;
 // Where a pg parameter stands in SQL: after a comparison, a list or call opener, or a clause keyword.
@@ -70,7 +128,7 @@ export const CODE_PATTERNS = [
     { match: re(/(?<![\w$])eval\s*\(/), type: 'Eval Usage', severity: 'medium', desc: 'eval() can execute arbitrary code' },
     { match: re(/innerHTML\s*=/), type: 'innerHTML', severity: 'medium', desc: 'XSS risk with innerHTML' },
     { match: re(/dangerouslySetInnerHTML/), type: 'React XSS', severity: 'medium', desc: 'React XSS risk' },
-    { match: re(/child_process.*exec/), type: 'Command Injection', severity: 'high', desc: 'Possible command injection' },
+    { match: line => /child_process.*exec/.test(line) || interpolatedExec(line), type: 'Command Injection', severity: 'high', desc: 'Possible command injection' },
     { match: line => sqlInterpolation(line) && sqlInterpolation(withoutPlaceholders(line)), type: 'SQL Injection', severity: 'high', desc: 'Possible SQL injection' },
 ];
 /**

package/v3/@claude-flow/cli/dist/src/commands/security.d.ts

@@ -5,6 +5,30 @@
  * Created with ❤️ by ruv.io
  */
 import type { Command } from '../types.js';
+/**
+ * #4124: `npm audit` can fail without exiting through the vulnerability path.
+ * In a pnpm/yarn/bun project there is no package-lock.json, so it prints
+ * `{"error":{"code":"ENOLOCK",...}}`. That has no `vulnerabilities` key, and
+ * both `scan` and `cve` used to read it as a clean tree. Only a report with a
+ * `vulnerabilities` object counts as a scan; anything else is "could not scan".
+ */
+type NpmAuditVuln = {
+    severity: string;
+    via: Array<{
+        title?: string;
+        url?: string;
+        source?: number;
+        name?: string;
+    } | string>;
+};
+export type NpmAuditResult = {
+    ok: true;
+    vulnerabilities: Record<string, NpmAuditVuln>;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function interpretNpmAudit(raw: string, dir?: string): NpmAuditResult;
 export declare const securityCommand: Command;
 export default securityCommand;
 //# sourceMappingURL=security.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/security.js

@@ -155,6 +155,7 @@ const scanCommand = {
             spinner.start();
         const findings = [];
         let criticalCount = 0, highCount = 0, mediumCount = 0, lowCount = 0;
+        let depsSkipped;
         try {
             const fs = await import('fs');
             const path = await import('path');
@@ -178,35 +179,41 @@ const scanCommand = {
                             // npm audit exits non-zero when vulnerabilities found — stdout still has JSON
                             auditResult = (auditErr instanceof Error && 'stdout' in auditErr ? auditErr.stdout : undefined) || '{}';
                         }
-                        try {
-                            const audit = JSON.parse(auditResult);
-                            if (audit.vulnerabilities) {
-                                for (const [pkg, vuln] of Object.entries(audit.vulnerabilities)) {
-                                    const sev = vuln.severity || 'low';
-                                    const title = Array.isArray(vuln.via) && vuln.via[0]?.title ? vuln.via[0].title : 'Vulnerability';
-                                    if (sev === 'critical')
-                                        criticalCount++;
-                                    else if (sev === 'high')
-                                        highCount++;
-                                    else if (sev === 'moderate' || sev === 'medium')
-                                        mediumCount++;
-                                    else
-                                        lowCount++;
-                                    findings.push({
-                                        severity: sev === 'critical' ? 'critical' :
-                                            sev === 'high' ? 'high' :
-                                                sev === 'moderate' || sev === 'medium' ? 'medium' : 'low',
-                                        type: 'Dependency CVE',
-                                        location: `package.json:${pkg}`,
-                                        description: title.substring(0, 35),
-                                    });
-                                }
+                        const audit = interpretNpmAudit(auditResult, path.resolve(target));
+                        if (!audit.ok) {
+                            depsSkipped = audit.reason;
+                        }
+                        else {
+                            for (const [pkg, vuln] of Object.entries(audit.vulnerabilities)) {
+                                const sev = vuln.severity || 'low';
+                                const first = Array.isArray(vuln.via) ? vuln.via[0] : undefined;
+                                const title = typeof first === 'object' && first?.title ? first.title : 'Vulnerability';
+                                if (sev === 'critical')
+                                    criticalCount++;
+                                else if (sev === 'high')
+                                    highCount++;
+                                else if (sev === 'moderate' || sev === 'medium')
+                                    mediumCount++;
+                                else
+                                    lowCount++;
+                                findings.push({
+                                    severity: sev === 'critical' ? 'critical' :
+                                        sev === 'high' ? 'high' :
+                                            sev === 'moderate' || sev === 'medium' ? 'medium' : 'low',
+                                    type: 'Dependency CVE',
+                                    location: `package.json:${pkg}`,
+                                    description: title.substring(0, 35),
+                                });
                             }
                         }
-                        catch { /* JSON parse failed, no vulns */ }
                     }
+                    else {
+                        depsSkipped = 'No package.json found in the scan target; dependency scan could not run.';
+                    }
+                }
+                catch (err) {
+                    depsSkipped = `npm audit could not run: ${err instanceof Error ? err.message : String(err)}`;
                 }
-                catch { /* npm audit failed */ }
             }
             // Phase 2: Scan for hardcoded secrets
             if (scanType === 'all' || scanType === 'code') {
@@ -342,9 +349,14 @@ const scanCommand = {
                         output.writeln(output.dim(`... and ${findings.length - 20} more issues`));
                     }
                 }
+                else if (depsSkipped) {
+                    output.writeln(output.warning('No issues found by the checks that ran, but the dependency scan did not run.'));
+                }
                 else {
                     output.writeln(output.success('No security issues found!'));
                 }
+                if (depsSkipped)
+                    output.writeln(output.warning(`Dependency scan skipped: ${depsSkipped}`));
                 output.writeln();
                 output.printBox([
                     `Target: ${target}`,
@@ -367,6 +379,7 @@ const scanCommand = {
                     low: lowCount,
                     total: findings.length,
                 },
+                ...(depsSkipped ? { incomplete: true, skipped: { deps: depsSkipped } } : {}),
                 findings,
             };
             // Persist the scan result so downstream consumers (the statusline's
@@ -408,6 +421,11 @@ const scanCommand = {
                 output.printJson(record);
             else if (outputFormat === 'sarif')
                 output.printJson(scanSarif(findings));
+            if (depsSkipped) {
+                if (outputFormat !== 'text')
+                    output.printError(`Dependency scan skipped: ${depsSkipped}`);
+                return { success: false, exitCode: 2 };
+            }
             return { success: findings.length === 0 || (criticalCount === 0 && highCount === 0) };
         }
         catch (error) {
@@ -418,6 +436,36 @@ const scanCommand = {
         }
     },
 };
+export function interpretNpmAudit(raw, dir) {
+    let audit;
+    try {
+        audit = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'npm audit did not return a JSON report.' };
+    }
+    if (audit && typeof audit === 'object' && audit.error) {
+        const code = typeof audit.error.code === 'string' ? audit.error.code : 'error';
+        const summary = typeof audit.error.summary === 'string' ? audit.error.summary : 'npm audit failed.';
+        return { ok: false, reason: `npm audit failed (${code}): ${summary}${code === 'ENOLOCK' ? auditHint(dir) : ''}` };
+    }
+    if (!audit || typeof audit !== 'object' || !audit.vulnerabilities || typeof audit.vulnerabilities !== 'object' || Array.isArray(audit.vulnerabilities)) {
+        return { ok: false, reason: 'npm audit returned no vulnerability report.' };
+    }
+    return { ok: true, vulnerabilities: audit.vulnerabilities };
+}
+function auditHint(dir) {
+    if (!dir)
+        return '';
+    const has = (f) => existsSync(resolvePath(dir, f));
+    if (has('pnpm-lock.yaml'))
+        return ' This is a pnpm project: run `pnpm audit` instead.';
+    if (has('yarn.lock'))
+        return ' This is a yarn project: run `yarn npm audit` (Berry) or `yarn audit` (v1) instead.';
+    if (has('bun.lock') || has('bun.lockb'))
+        return ' This is a bun project: run `bun audit` instead.';
+    return ' Create one with `npm i --package-lock-only`, or use your package manager\'s audit.';
+}
 // CVE subcommand
 const cveCommand = {
     name: 'cve',
@@ -451,22 +499,20 @@ const cveCommand = {
             // npm audit exits non-zero when vulnerabilities found — stdout still has JSON
             auditJson = (e instanceof Error && 'stdout' in e ? e.stdout : '') || '{}';
         }
-        let audit;
-        try {
-            audit = JSON.parse(auditJson);
-        }
-        catch {
-            output.writeln(output.warning('⚠ Could not parse `npm audit --json` output.'));
-            output.writeln(output.dim('Make sure you are inside a project with a package.json.'));
+        const audit = interpretNpmAudit(auditJson, process.cwd());
+        if (!audit.ok) {
+            output.writeln(output.warning(`⚠ Could not check dependencies: ${audit.reason}`));
+            output.writeln(output.dim('No result is reported rather than a false all-clear.'));
             return { success: false, exitCode: 2 };
         }
-        const vulns = audit.vulnerabilities || {};
+        const vulns = audit.vulnerabilities;
         const cveRows = [];
         const CVE_RE = /CVE-\d{4}-\d{4,7}/g;
         for (const [pkg, v] of Object.entries(vulns)) {
             const sev = v.severity || 'low';
-            const titles = (v.via || []).filter((x) => typeof x === 'object' && x?.title).map((x) => x.title);
-            const urls = (v.via || []).filter((x) => typeof x === 'object' && x?.url).map((x) => x.url);
+            const via = (v.via || []).filter((x) => typeof x === 'object' && x !== null);
+            const titles = via.filter((x) => x.title).map((x) => x.title);
+            const urls = via.filter((x) => x.url).map((x) => x.url);
             const allText = `${titles.join(' ')} ${urls.join(' ')}`;
             const cveIds = Array.from(new Set(allText.match(CVE_RE) || []));
             cveRows.push({ pkg, severity: sev, cveIds, title: titles[0] || 'Vulnerability', url: urls[0] });

package/v3/@claude-flow/cli/dist/src/commands/tui.d.ts

@@ -1,6 +1,15 @@
 import type { Command } from '../types.js';
 /** `<own install>/plugins/ruflo-console/dist/tui.mjs`, the first that exists. */
 export declare function locateTuiBundle(startDir?: string): string | null;
+/** 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 declare function lookFlags(flags: Record<string, unknown> | undefined): {
+    look?: string;
+    fps?: number;
+    anim?: boolean;
+    pictures?: boolean;
+    boot?: boolean;
+    mouse?: boolean;
+};
 /** 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 declare function aiPage(flags: Record<string, unknown> | undefined): {
     model?: string;

package/v3/@claude-flow/cli/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/v3/@claude-flow/cli/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;