Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

fix(helper-refresh): also refresh ~/.claude/helpers so global statusline picks up new features

ruvnet8306ad8fe52b
diff --git a/package.json b/package.json
index 86f4b117db..485ca273c7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.31.2",
+ "version": "3.31.3",
"description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "dist/index.js",
"type": "module",
diff --git a/ruflo/package.json b/ruflo/package.json
index fefc9cc292..5fefdcd78b 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.31.2",
+ "version": "3.31.3",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
diff --git a/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts b/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
index e04584abec..1bf16801e5 100644
--- a/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
+++ b/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
@@ -149,6 +149,74 @@ describe('autoRefreshHelpersIfStale', () => {
expect(readFileSync(join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim()).toBe(futureVersion);
});
+ it('alsoRefreshGlobal:true refreshes ~/.claude/helpers under a redirected HOME (regression: pre-3.31.3 the global copy never refreshed, so the 2026-07-13 promo row never reached existing installs)', async () => {
+ const { cwd } = makeProject(); // project dir is a real ruflo project so the project pass has something to do
+ const projectHelpers = join(cwd, '.claude', 'helpers');
+ writeFileSync(join(projectHelpers, 'hook-handler.cjs'), 'intelligence.feedback(true); // OLD project\n');
+ writeFileSync(join(projectHelpers, HELPERS_STAMP_FILE), '0.0.1-old');
+
+ // Redirect HOME so we don't touch the developer's real ~/.claude/helpers.
+ // Populate the "global" helpers dir with a stale-stamped hook-handler.
+ const fakeHome = mkdtempSync(join(tmpdir(), 'helper-refresh-home-'));
+ const globalHelpers = join(fakeHome, '.claude', 'helpers');
+ mkdirSync(globalHelpers, { recursive: true });
+ writeFileSync(join(globalHelpers, 'hook-handler.cjs'), 'intelligence.feedback(true); // OLD global\n');
+ writeFileSync(join(globalHelpers, HELPERS_STAMP_FILE), '0.0.1-old');
+
+ const { sourceDir, pubkeyPem } = makeSignedSource(version);
+ const savedHome = process.env.HOME;
+ const savedUserProfile = process.env.USERPROFILE;
+ process.env.HOME = fakeHome;
+ process.env.USERPROFILE = fakeHome; // Node's os.homedir() reads USERPROFILE on Windows
+ try {
+ const r = await autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: sourceDir,
+ pubkeyPemOverride: pubkeyPem,
+ alsoRefreshGlobal: true,
+ });
+ // Project pass fired (top-level fields are the project result β€” API compat)
+ expect(r.refreshed).toBe(true);
+ expect(r.to).toBe(version);
+ // Global pass ALSO fired, carried in the new `global` field
+ expect(r.global?.refreshed).toBe(true);
+ expect(r.global?.from).toBe('0.0.1-old');
+ expect(r.global?.to).toBe(version);
+ // Global hook-handler was actually rewritten (not just the stamp)
+ const refreshedGlobal = readFileSync(join(globalHelpers, 'hook-handler.cjs'), 'utf-8');
+ expect(refreshedGlobal).toMatch(/toolFailed/);
+ expect(refreshedGlobal).not.toContain('// OLD global');
+ } finally {
+ if (savedHome === undefined) delete process.env.HOME; else process.env.HOME = savedHome;
+ if (savedUserProfile === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = savedUserProfile;
+ }
+ });
+
+ it('alsoRefreshGlobal defaults to false β€” tests without the flag never touch $HOME (invariant that keeps every OTHER test in this file safe)', async () => {
+ const { cwd, helpersDir } = makeProject();
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), 'intelligence.feedback(true);\n');
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '0.0.1-old');
+
+ // Redirect HOME to an empty scratch dir with no .claude/helpers. If the
+ // global pass fired despite the flag being unset, this test would either
+ // create files under fakeHome (assertion below catches it) or surface a
+ // `global` field on the result (also checked).
+ const fakeHome = mkdtempSync(join(tmpdir(), 'helper-refresh-should-not-touch-home-'));
+ const savedHome = process.env.HOME;
+ const savedUserProfile = process.env.USERPROFILE;
+ process.env.HOME = fakeHome;
+ process.env.USERPROFILE = fakeHome;
+ try {
+ const { sourceDir, pubkeyPem } = makeSignedSource(version);
+ const r = await autoRefreshHelpersIfStale(cwd, { sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });
+ expect(r.refreshed).toBe(true); // project pass still fired
+ expect(r.global).toBeUndefined(); // global pass DID NOT fire
+ expect(existsSync(join(fakeHome, '.claude'))).toBe(false); // never scaffolded under HOME
+ } finally {
+ if (savedHome === undefined) delete process.env.HOME; else process.env.HOME = savedHome;
+ if (savedUserProfile === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = savedUserProfile;
+ }
+ });
+
it('never downgrades β€” an EQUAL-but-differently-formatted stamp is a no-op', async () => {
// e.g. stamp has a build/prerelease suffix that string-compares unequal
// to the installed version but is semver-equal or newer.
diff --git a/v3/@claude-flow/cli/package-lock.json b/v3/@claude-flow/cli/package-lock.json
index 7dc98c5ffd..f6cae85ae0 100644
--- a/v3/@claude-flow/cli/package-lock.json
+++ b/v3/@claude-flow/cli/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@claude-flow/cli",
- "version": "3.31.2",
+ "version": "3.31.3",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@claude-flow/cli",
- "version": "3.31.2",
+ "version": "3.31.3",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index e5bc66f4c4..4656c940c0 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.31.2",
+ "version": "3.31.3",
"type": "module",
"description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/cli/src/index.ts b/v3/@claude-flow/cli/src/index.ts
index 2408f46122..54cdc7f6f4 100644
--- a/v3/@claude-flow/cli/src/index.ts
+++ b/v3/@claude-flow/cli/src/index.ts
@@ -142,7 +142,16 @@ export class CLI {
if (commandPath[0] !== 'init' && commandPath[0] !== 'update') {
try {
const { autoRefreshHelpersIfStale } = await import('./init/helper-refresh.js');
- const r = await autoRefreshHelpersIfStale(process.cwd());
+ // alsoRefreshGlobal:true β€” refresh ~/.claude/helpers too, not just
+ // <cwd>/.claude/helpers. Fixes the "promo row missing on remote
+ // installs" bug where Claude Code's global settings.json falls back
+ // to ~/.claude/helpers/statusline.cjs (executor.ts:460-462) and that
+ // file was frozen at whatever version was current when the user
+ // last ran `ruflo init` β€” pre-3.31.3 nothing refreshed it, so any
+ // helpers change (e.g. the 2026-07-13 Line-3 funnel row addition)
+ // never reached existing installs. Same forward-only semver.gte
+ // guard applies to the global pass.
+ const r = await autoRefreshHelpersIfStale(process.cwd(), { alsoRefreshGlobal: true });
if (r.blocked) {
// Integrity failure = potential on-disk tampering of hook code. Warn
// loudly (not silent) β€” the existing project helpers were left intact.
@@ -150,6 +159,11 @@ export class CLI {
} else if (r.refreshed && this.output.isVerbose()) {
this.output.printDebug(`Refreshed .claude/helpers (${r.from} β†’ ${r.to})`);
}
+ if (r.global?.refreshed && this.output.isVerbose()) {
+ this.output.printDebug(`Refreshed ~/.claude/helpers (${r.global.from} β†’ ${r.global.to})`);
+ } else if (r.global?.blocked && r.global.blocked !== r.blocked) {
+ this.output.printWarning(`Skipped ~/.claude/helpers auto-refresh β€” ${r.global.blocked}.`);
+ }
} catch { /* silent */ }
// ADR-177: adopt a signed proven-configuration champion if the package
diff --git a/v3/@claude-flow/cli/src/init/helper-refresh.ts b/v3/@claude-flow/cli/src/init/helper-refresh.ts
index 663ee244b8..a6d2f28c0c 100644
--- a/v3/@claude-flow/cli/src/init/helper-refresh.ts
+++ b/v3/@claude-flow/cli/src/init/helper-refresh.ts
@@ -14,6 +14,7 @@
* heavy generators only on the rare fallback path (source dir unresolvable).
*/
import * as fs from 'fs';
+import * as os from 'os';
import * as path from 'path';
import { fileURLToPath } from 'url';
import { createRequire } from 'module';
@@ -218,50 +219,131 @@ async function writeCriticalHelpers(
* signed fixture and get real, deterministic coverage of the verify β†’ hash β†’
* copy logic without depending on that.
*/
-export async function autoRefreshHelpersIfStale(
- cwd: string,
- opts: { sourceDirOverride?: string; pubkeyPemOverride?: string; versionOverride?: string } = {},
+async function refreshOneHelpersDir(
+ helpersDir: string,
+ version: string,
+ opts: { sourceDirOverride?: string; pubkeyPemOverride?: string },
): Promise<{ refreshed: boolean; from?: string; to?: string; blocked?: string }> {
- try {
- const helpersDir = path.join(cwd, '.claude', 'helpers');
- if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs'))) return { refreshed: false };
+ if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs'))) return { refreshed: false };
- // .LOCKED marker: users developing ruflo itself (or any project with
- // hand-maintained helpers) can place a `.LOCKED` file at
- // `.claude/helpers/.LOCKED` to opt this project out of auto-refresh
- // entirely. Fixes the observed-live concurrent-session clobber where a
- // sibling Claude Code session running a stale cached CLI would overwrite
- // hand-edited helpers on this repo (CLAUDE.md "Concurrent-session helper
- // corruption"). Existing semver.gte guard below still fires for normal
- // installs β€” this is the escape hatch for the small set of users editing
- // helpers directly. Delete the file to re-enable refresh.
- if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
- return { refreshed: false, blocked: '.LOCKED marker present β€” refresh skipped (delete to re-enable)' };
- }
+ // .LOCKED marker: users developing ruflo itself (or any project with
+ // hand-maintained helpers) can place a `.LOCKED` file at
+ // `.claude/helpers/.LOCKED` to opt out of auto-refresh entirely. Fixes the
+ // observed-live concurrent-session clobber where a sibling Claude Code
+ // session running a stale cached CLI would overwrite hand-edited helpers
+ // on this repo (CLAUDE.md "Concurrent-session helper corruption"). The
+ // existing semver.gte guard below still fires for normal installs β€” this
+ // is the escape hatch for the small set of users editing helpers directly.
+ // Applies to whichever dir this call is refreshing (project or global).
+ if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
+ return { refreshed: false, blocked: '.LOCKED marker present β€” refresh skipped (delete to re-enable)' };
+ }
- // Also honor an env-level opt-out for CI / release-time scripting that
- // knows it doesn't want any writes to helpers this run.
+ let stamped = '';
+ try { stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim(); } catch { /* pre-feature: unstamped */ }
+ if (stamped === version) return { refreshed: false }; // up to date β€” fast path
+ if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
+ // Stamped version is already >= what this binary reports β€” refreshing
+ // would silently DOWNGRADE the helpers. Skip, untouched.
+ return { refreshed: false };
+ }
+ const res = await writeCriticalHelpers(helpersDir, version, {
+ sourceDirOverride: opts.sourceDirOverride,
+ pubkeyPemOverride: opts.pubkeyPemOverride,
+ });
+ if (res.blocked) return { refreshed: false, blocked: res.blocked };
+ return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+}
+
+/**
+ * On CLI startup, refresh critical helpers if their stamp is older than the
+ * installed CLI version. Two passes:
+ *
+ * 1. **Project pass** β€” `<cwd>/.claude/helpers/`. Always attempted. The
+ * original behavior; project statuslines pin to a stamp per repo.
+ *
+ * 2. **Global pass** β€” `~/.claude/helpers/`. Opt-in via `alsoRefreshGlobal`.
+ * Fixes the "promo row missing on remote installs" bug: `ruflo init`
+ * writes helpers to `~/.claude/helpers/` too so Claude Code's global
+ * settings.json statusLine can fall back to them (executor.ts:460-462),
+ * but nothing ever REFRESHED that global copy β€” so any install predating
+ * a helpers change (e.g. the 2026-07-13 funnel/promo Line-3 addition)
+ * stayed frozen at the pre-feature statusline forever, even after `npm
+ * i -g @claude-flow/cli@latest`. The global pass fixes that on the next
+ * `ruflo <anything>` invocation. Same forward-only `semver.gte` guard
+ * protects against downgrade by a stale cached CLI.
+ *
+ * `alsoRefreshGlobal` defaults FALSE so tests don't touch the developer's
+ * real `~/.claude/helpers/`. The real CLI entry (src/index.ts) passes
+ * `true` to activate the global pass in production.
+ *
+ * Best-effort, never throws. No-op for a helpers dir that doesn't already
+ * contain a `hook-handler.cjs` β€” never creates files in an unrelated dir.
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector β€” confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) would see its own older version !=
+ * the project's newer stamp and silently overwrite hand-fixed
+ * `hook-handler.cjs`/`intelligence.cjs` with its own older, already-superseded
+ * bundled copies. Comparing with `semver.gt` instead of `!==` makes that
+ * impossible: an older or equal installed version is always a no-op,
+ * regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled
+ * to THIS repo's actual current `.claude/helpers` + its real Ed25519
+ * signature β€” fine for production (that coupling to the real source IS the
+ * point), but it means a test exercising that path for real would only pass
+ * when this repo's manifest happens to be currently re-signed, which is a
+ * separately-gated, occasionally-stale publish-time step. `sourceDirOverride`
+ * + `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify β†’ hash
+ * β†’ copy logic without depending on that.
+ *
+ * Return shape: the project-pass result is the top-level object (backwards-
+ * compat with pre-3.31.3 callers). If the global pass ran, its own result is
+ * carried in the optional `global` field.
+ */
+export async function autoRefreshHelpersIfStale(
+ cwd: string,
+ opts: {
+ sourceDirOverride?: string;
+ pubkeyPemOverride?: string;
+ versionOverride?: string;
+ alsoRefreshGlobal?: boolean;
+ } = {},
+): Promise<{
+ refreshed: boolean;
+ from?: string;
+ to?: string;
+ blocked?: string;
+ global?: { refreshed: boolean; from?: string; to?: string; blocked?: string };
+}> {
+ try {
+ // Env-level opt-out β€” applies to BOTH project and global passes.
if (/^(1|true|on|yes)$/i.test(String(process.env.RUFLO_HELPERS_LOCKED || ''))) {
return { refreshed: false, blocked: 'RUFLO_HELPERS_LOCKED env β€” refresh skipped' };
}
const version = opts.versionOverride ?? getInstalledCliVersion();
- let stamped = '';
- try { stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim(); } catch { /* pre-feature: unstamped */ }
- if (stamped === version) return { refreshed: false }; // up to date β€” fast path
- if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
- // Stamped version is already >= what this binary reports β€” refreshing
- // would silently DOWNGRADE the project's helpers. Skip, untouched.
- return { refreshed: false };
+ const projectDir = path.join(cwd, '.claude', 'helpers');
+ const projectResult = await refreshOneHelpersDir(projectDir, version, opts);
+
+ // Global pass β€” opt-in only; test callers omit alsoRefreshGlobal to avoid
+ // touching the developer's real ~/.claude/helpers.
+ if (opts.alsoRefreshGlobal) {
+ const globalDir = path.join(os.homedir(), '.claude', 'helpers');
+ // Skip if project === global (e.g. someone invoked ruflo from $HOME
+ // and $HOME happens to be a ruflo project β€” refreshing twice is
+ // redundant AND could second-guess the first pass's result).
+ if (path.resolve(globalDir) !== path.resolve(projectDir)) {
+ const globalResult = await refreshOneHelpersDir(globalDir, version, opts);
+ return { ...projectResult, global: globalResult };
+ }
}
- const res = await writeCriticalHelpers(helpersDir, version, {
- sourceDirOverride: opts.sourceDirOverride,
- pubkeyPemOverride: opts.pubkeyPemOverride,
- });
- // A blocked refresh is a SECURITY signal (tampered source/manifest) β€” surface
- // it, don't advance the stamp, and leave the project's existing helpers intact.
- if (res.blocked) return { refreshed: false, blocked: res.blocked };
- return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+ return projectResult;
} catch {
return { refreshed: false };
}