π 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(helper-refresh): also refresh ~/.claude/helpers so global statusline picks up new features
ruvnet8306ad8fe52b
diff --git a/package.json b/package.jsonindex 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.jsonindex 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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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 packagediff --git a/v3/@claude-flow/cli/src/init/helper-refresh.ts b/v3/@claude-flow/cli/src/init/helper-refresh.tsindex 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 };}