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(cli): serialize helper refreshes across processes

dajiaohuang0c73bab4d04e
diff --git a/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts b/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
index 1bf16801e5..61b3185a22 100644
--- a/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
+++ b/v3/@claude-flow/cli/__tests__/helper-refresh.test.ts
@@ -19,13 +19,18 @@
* when it does.
*/
import { describe, it, expect, beforeEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { generateKeyPairSync, sign as edSign } from 'node:crypto';
import * as semver from 'semver';
-import { autoRefreshHelpersIfStale, getInstalledCliVersion, HELPERS_STAMP_FILE } from '../src/init/helper-refresh.js';
+import {
+ autoRefreshHelpersIfStale,
+ getInstalledCliVersion,
+ HELPERS_REFRESH_LOCK_FILE,
+ HELPERS_STAMP_FILE,
+} from '../src/init/helper-refresh.js';
import { canonicalManifestBytes, sha256Hex } from '../src/init/helper-signing.js';
function makeProject(): { cwd: string; helpersDir: string } {
@@ -41,9 +46,11 @@ function makeProject(): { cwd: string; helpersDir: string } {
* manifest for it. Returns the source dir and the matching public key PEM
* to inject via `pubkeyPemOverride`.
*/
-function makeSignedSource(version: string): { sourceDir: string; pubkeyPem: string } {
+function makeSignedSource(
+ version: string,
+ content = 'intelligence.feedback(!toolFailed); // NEW, real failure capture\n',
+): { sourceDir: string; pubkeyPem: string } {
const sourceDir = mkdtempSync(join(tmpdir(), 'helper-refresh-source-'));
- const content = 'intelligence.feedback(!toolFailed); // NEW, real failure capture\n';
writeFileSync(join(sourceDir, 'hook-handler.cjs'), content);
const { publicKey, privateKey } = generateKeyPairSync('ed25519');
@@ -57,6 +64,18 @@ function makeSignedSource(version: string): { sourceDir: string; pubkeyPem: stri
return { sourceDir, pubkeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString() };
}
+function makeWriteGate(): {
+ reached: Promise<void>;
+ release: () => void;
+ beforeWrite: () => Promise<void>;
+} {
+ let signalReached!: () => void;
+ const reached = new Promise<void>((resolve) => { signalReached = resolve; });
+ let release!: () => void;
+ const mayWrite = new Promise<void>((resolve) => { release = resolve; });
+ return { reached, release, beforeWrite: async () => { signalReached(); await mayWrite; } };
+}
+
describe('autoRefreshHelpersIfStale', () => {
let version: string;
beforeEach(() => { version = getInstalledCliVersion(); });
@@ -229,4 +248,104 @@ describe('autoRefreshHelpersIfStale', () => {
expect(r.refreshed).toBe(false);
expect(readFileSync(join(helpersDir, 'hook-handler.cjs'), 'utf-8')).toBe(marker);
});
+
+ it.each([
+ ['older checks first', '2.0.0', 'OLDER-HANDLER', '3.0.0', 'NEWER-HANDLER'],
+ ['newer checks first', '3.0.0', 'NEWER-HANDLER', '2.0.0', 'OLDER-HANDLER'],
+ ])('serializes competing refreshes when %s', async (_label, firstVersion, firstContent, secondVersion, secondContent) => {
+ const { cwd, helpersDir } = makeProject();
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), 'INITIAL-HANDLER');
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '1.0.0');
+ const first = makeSignedSource(firstVersion, firstContent);
+ const second = makeSignedSource(secondVersion, secondContent);
+ const gate = makeWriteGate();
+
+ const firstRefresh = autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: first.sourceDir,
+ pubkeyPemOverride: first.pubkeyPem,
+ versionOverride: firstVersion,
+ beforeWriteOverride: gate.beforeWrite,
+ });
+ await gate.reached;
+ const secondRefresh = autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: second.sourceDir,
+ pubkeyPemOverride: second.pubkeyPem,
+ versionOverride: secondVersion,
+ });
+ gate.release();
+ await Promise.all([firstRefresh, secondRefresh]);
+
+ expect(readFileSync(join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim()).toBe('3.0.0');
+ expect(readFileSync(join(helpersDir, 'hook-handler.cjs'), 'utf-8')).toBe('NEWER-HANDLER');
+ expect(readdirSync(helpersDir).filter((name) => name.includes('.tmp-'))).toEqual([]);
+ });
+
+ it('does not let a same-version waiter replace the completed helper set', async () => {
+ const { cwd, helpersDir } = makeProject();
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), 'INITIAL-HANDLER');
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '1.0.0');
+ const first = makeSignedSource('2.0.0', 'FIRST-SAME-VERSION-HANDLER');
+ const second = makeSignedSource('2.0.0', 'SECOND-SAME-VERSION-HANDLER');
+
+ const gate = makeWriteGate();
+ const firstRefresh = autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: first.sourceDir,
+ pubkeyPemOverride: first.pubkeyPem,
+ versionOverride: '2.0.0',
+ beforeWriteOverride: gate.beforeWrite,
+ });
+ await gate.reached;
+
+ const secondRefresh = autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: second.sourceDir,
+ pubkeyPemOverride: second.pubkeyPem,
+ versionOverride: '2.0.0',
+ });
+ gate.release();
+ const [, secondResult] = await Promise.all([firstRefresh, secondRefresh]);
+
+ expect(secondResult.refreshed).toBe(false);
+ expect(readFileSync(join(helpersDir, 'hook-handler.cjs'), 'utf-8')).toBe('FIRST-SAME-VERSION-HANDLER');
+ });
+
+ it('fails closed while another live process owns the refresh lock', async () => {
+ const { cwd, helpersDir } = makeProject();
+ const marker = 'LIVE-LOCK-HANDLER';
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), marker);
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '1.0.0');
+ const lockPath = join(helpersDir, HELPERS_REFRESH_LOCK_FILE);
+ writeFileSync(lockPath, JSON.stringify({ pid: process.pid, token: 'test-owner' }));
+
+ try {
+ const r = await autoRefreshHelpersIfStale(cwd, {
+ versionOverride: '2.0.0',
+ lockWaitMsOverride: 0,
+ });
+ expect(r.refreshed).toBe(false);
+ expect(r.blocked).toMatch(/already in progress/);
+ expect(readFileSync(join(helpersDir, 'hook-handler.cjs'), 'utf-8')).toBe(marker);
+ } finally {
+ unlinkSync(lockPath);
+ }
+ });
+
+ it('recovers an abandoned lock created before owner metadata was written', async () => {
+ const { cwd, helpersDir } = makeProject();
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), 'INITIAL-HANDLER');
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '1.0.0');
+ const lockPath = join(helpersDir, HELPERS_REFRESH_LOCK_FILE);
+ writeFileSync(lockPath, '');
+ const source = makeSignedSource('2.0.0', 'RECOVERED-HANDLER');
+
+ const r = await autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: source.sourceDir,
+ pubkeyPemOverride: source.pubkeyPem,
+ versionOverride: '2.0.0',
+ malformedLockStaleMsOverride: 0,
+ });
+
+ expect(r.refreshed).toBe(true);
+ expect(readFileSync(join(helpersDir, 'hook-handler.cjs'), 'utf-8')).toBe('RECOVERED-HANDLER');
+ expect(existsSync(lockPath)).toBe(false);
+ });
});
diff --git a/v3/@claude-flow/cli/src/init/helper-refresh.ts b/v3/@claude-flow/cli/src/init/helper-refresh.ts
index a6d2f28c0c..f31b35c23e 100644
--- a/v3/@claude-flow/cli/src/init/helper-refresh.ts
+++ b/v3/@claude-flow/cli/src/init/helper-refresh.ts
@@ -55,6 +55,22 @@ function findPackageRoot(startDir: string, maxUp = 6): string | null {
}
export const HELPERS_STAMP_FILE = '.helpers-version';
+export const HELPERS_REFRESH_LOCK_FILE = '.helpers-refresh.lock';
+const DEFAULT_LOCK_WAIT_MS = 2_000;
+const DEFAULT_LOCK_RETRY_MS = 10;
+const DEFAULT_MALFORMED_LOCK_STALE_MS = 5 * 60_000;
+let tempFileCounter = 0;
+interface RefreshOptions {
+ sourceDirOverride?: string;
+ pubkeyPemOverride?: string;
+ versionOverride?: string;
+ alsoRefreshGlobal?: boolean;
+ beforeWriteOverride?: () => void | Promise<void>;
+ lockWaitMsOverride?: number;
+ lockRetryMsOverride?: number;
+ malformedLockStaleMsOverride?: number;
+}
+
/**
* ruflo-owned helpers that carry hook logic (or the render surface for the
* funnel disclosure row) and must track the package version. Adding to this
@@ -70,6 +86,119 @@ export const CRITICAL_HELPERS = [
'statusline.cjs',
];
+function errorCode(error: unknown): string | undefined {
+ return typeof error === 'object' && error !== null && 'code' in error
+ ? String((error as { code?: unknown }).code)
+ : undefined;
+}
+
+function processIsAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (error) {
+ return errorCode(error) !== 'ESRCH';
+ }
+}
+
+function removeAbandonedLock(lockPath: string, malformedStaleMs: number): boolean {
+ try {
+ const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as { pid?: unknown };
+ if (Number.isSafeInteger(parsed.pid) && Number(parsed.pid) > 0) {
+ if (processIsAlive(Number(parsed.pid))) return false;
+ fs.unlinkSync(lockPath);
+ return true;
+ }
+ } catch (error) {
+ if (errorCode(error) === 'ENOENT') return true;
+ }
+
+ // A process can die after the exclusive create but before writing metadata.
+ // Only reclaim such malformed locks after a generous age; valid locks with a
+ // live PID are never age-evicted, so a slow refresh cannot lose ownership.
+ try {
+ if (Date.now() - fs.statSync(lockPath).mtimeMs >= malformedStaleMs) {
+ fs.unlinkSync(lockPath);
+ return true;
+ }
+ } catch (error) {
+ if (errorCode(error) === 'ENOENT') return true;
+ }
+ return false;
+}
+
+async function acquireRefreshLock(
+ helpersDir: string,
+ opts: RefreshOptions,
+): Promise<(() => void) | null> {
+ const lockPath = path.join(helpersDir, HELPERS_REFRESH_LOCK_FILE);
+ const waitMs = opts.lockWaitMsOverride ?? DEFAULT_LOCK_WAIT_MS;
+ const retryMs = opts.lockRetryMsOverride ?? DEFAULT_LOCK_RETRY_MS;
+ const malformedStaleMs = opts.malformedLockStaleMsOverride ?? DEFAULT_MALFORMED_LOCK_STALE_MS;
+ const deadline = Date.now() + Math.max(0, waitMs);
+
+ while (true) {
+ const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+ let fd: number | undefined;
+ let created = false;
+ try {
+ fd = fs.openSync(lockPath, 'wx');
+ created = true;
+ fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token }), 'utf-8');
+ fs.closeSync(fd);
+ fd = undefined;
+ return () => {
+ try {
+ const current = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as { token?: unknown };
+ if (current.token === token) fs.unlinkSync(lockPath);
+ } catch { /* best-effort release; a replaced lock is never removed */ }
+ };
+ } catch (error) {
+ if (fd !== undefined) {
+ try { fs.closeSync(fd); } catch { /* best-effort */ }
+ }
+ if (created) {
+ try { fs.unlinkSync(lockPath); } catch { /* best-effort */ }
+ }
+ if (errorCode(error) !== 'EEXIST') throw error;
+ if (removeAbandonedLock(lockPath, malformedStaleMs)) continue;
+ if (Date.now() >= deadline) return null;
+ await new Promise<void>((resolve) => setTimeout(resolve, Math.max(1, retryMs)));
+ }
+ }
+}
+
+function temporarySiblingPath(target: string): string {
+ tempFileCounter += 1;
+ return `${target}.tmp-${process.pid}-${Date.now()}-${tempFileCounter}`;
+}
+
+function atomicCopyFileSync(source: string, target: string, mode?: string): void {
+ const temporary = temporarySiblingPath(target);
+ try {
+ fs.copyFileSync(source, temporary, fs.constants.COPYFILE_EXCL);
+ if (mode) {
+ try { fs.chmodSync(temporary, mode); } catch { /* non-fatal */ }
+ }
+ fs.renameSync(temporary, target);
+ } finally {
+ try { fs.unlinkSync(temporary); } catch { /* already renamed or never created */ }
+ }
+}
+
+function atomicWriteFileSync(target: string, content: string, mode?: string): void {
+ const temporary = temporarySiblingPath(target);
+ try {
+ fs.writeFileSync(temporary, content, { encoding: 'utf-8', flag: 'wx' });
+ if (mode) {
+ try { fs.chmodSync(temporary, mode); } catch { /* non-fatal */ }
+ }
+ fs.renameSync(temporary, target);
+ } finally {
+ try { fs.unlinkSync(temporary); } catch { /* already renamed or never created */ }
+ }
+}
+
/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
export function getInstalledCliVersion(): string {
try {
@@ -149,13 +278,17 @@ async function writeCriticalHelpers(
let wrote = false;
for (const name of toCopy) {
const tp = path.join(helpersDir, name);
- fs.copyFileSync(path.join(source, name), tp);
- try { fs.chmodSync(tp, '755'); } catch { /* non-fatal */ }
+ atomicCopyFileSync(path.join(source, name), tp, '755');
wrote = true;
}
- try { fs.copyFileSync(path.join(source, HELPERS_MANIFEST_FILE), path.join(helpersDir, HELPERS_MANIFEST_FILE)); } catch { /* non-fatal */ }
+ try {
+ atomicCopyFileSync(
+ path.join(source, HELPERS_MANIFEST_FILE),
+ path.join(helpersDir, HELPERS_MANIFEST_FILE),
+ );
+ } catch { /* non-fatal */ }
if (wrote) {
- try { fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8'); } catch { /* non-fatal */ }
+ try { atomicWriteFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version); } catch { /* non-fatal */ }
}
return { wrote };
}
@@ -180,12 +313,11 @@ async function writeCriticalHelpers(
let wrote = false;
for (const [name, content] of Object.entries(files)) {
const tp = path.join(helpersDir, name);
- fs.writeFileSync(tp, content, 'utf-8');
- try { fs.chmodSync(tp, '755'); } catch { /* non-fatal */ }
+ atomicWriteFileSync(tp, content, '755');
wrote = true;
}
if (wrote) {
- try { fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8'); } catch { /* non-fatal */ }
+ try { atomicWriteFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version); } catch { /* non-fatal */ }
}
return { wrote };
}
@@ -204,9 +336,9 @@ async function writeCriticalHelpers(
* running `daemon start` (or any command) against THIS project directory
* 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.
+ * older, already-superseded bundled copies. The semver guard is therefore
+ * re-evaluated while holding a per-directory cross-process lock; otherwise
+ * an older process can pass the guard first but finish writing last.
*
* `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
* `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
@@ -219,10 +351,10 @@ async function writeCriticalHelpers(
* signed fixture and get real, deterministic coverage of the verify → hash →
* copy logic without depending on that.
*/
-async function refreshOneHelpersDir(
+async function refreshOneHelpersDirLocked(
helpersDir: string,
version: string,
- opts: { sourceDirOverride?: string; pubkeyPemOverride?: string },
+ opts: RefreshOptions,
): Promise<{ refreshed: boolean; from?: string; to?: string; blocked?: string }> {
if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs'))) return { refreshed: false };
@@ -247,6 +379,7 @@ async function refreshOneHelpersDir(
// would silently DOWNGRADE the helpers. Skip, untouched.
return { refreshed: false };
}
+ await opts.beforeWriteOverride?.();
const res = await writeCriticalHelpers(helpersDir, version, {
sourceDirOverride: opts.sourceDirOverride,
pubkeyPemOverride: opts.pubkeyPemOverride,
@@ -255,6 +388,27 @@ async function refreshOneHelpersDir(
return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
}
+async function refreshOneHelpersDir(
+ helpersDir: string,
+ version: string,
+ opts: RefreshOptions,
+): Promise<{ refreshed: boolean; from?: string; to?: string; blocked?: string }> {
+ if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs'))) return { refreshed: false };
+ try { if (fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim() === version) return { refreshed: false }; }
+ catch { /* unstamped: continue to the locked path */ }
+
+ const releaseLock = await acquireRefreshLock(helpersDir, opts);
+ if (!releaseLock) return { refreshed: false, blocked: 'helper refresh already in progress' };
+
+ try {
+ // Re-read the stamp and .LOCKED marker under the cross-process lock. A
+ // concurrent newer CLI may have completed while this caller waited.
+ return await refreshOneHelpersDirLocked(helpersDir, version, opts);
+ } finally {
+ releaseLock();
+ }
+}
+
/**
* On CLI startup, refresh critical helpers if their stamp is older than the
* installed CLI version. Two passes:
@@ -287,9 +441,9 @@ async function refreshOneHelpersDir(
* 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.
+ * bundled copies. The semver guard is therefore re-evaluated while holding a
+ * per-directory cross-process lock; otherwise an older process can pass the
+ * guard first but finish writing last.
*
* `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
* `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled
@@ -308,12 +462,7 @@ async function refreshOneHelpersDir(
*/
export async function autoRefreshHelpersIfStale(
cwd: string,
- opts: {
- sourceDirOverride?: string;
- pubkeyPemOverride?: string;
- versionOverride?: string;
- alsoRefreshGlobal?: boolean;
- } = {},
+ opts: RefreshOptions = {},
): Promise<{
refreshed: boolean;
from?: string;