🌊 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(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.tsindex 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: strireturn { 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.tsindex 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;