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(policy): remove orphaned atomic-write temp files under the policy lock (#3164)

Dragan Spiridonov42011db97754
diff --git a/v3/@claude-flow/cli/__tests__/policy-orphan-temp-reap-3164.test.ts b/v3/@claude-flow/cli/__tests__/policy-orphan-temp-reap-3164.test.ts
new file mode 100644
index 0000000000..e729558d70
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/policy-orphan-temp-reap-3164.test.ts
@@ -0,0 +1,125 @@
+import './helpers/isolated-policy-trust.js';
+/**
+ * #3164: `writeJsonAtomic` writes `<file>.<pid>.<uuid>.tmp` and renames it over
+ * the target. A writer killed between the two (SIGKILL from a caller's
+ * timeout, OOM) never reaches its `finally` cleanup, so a full-size copy of
+ * state.json or ledger-anchors.json stays in the policy directory forever.
+ * On a mature ledger each one is ~250 MB.
+ *
+ * Every writer of these files holds the project's state.lock, so a
+ * transaction that holds the lock may remove temp files of exactly those
+ * names. It must leave everything else alone: fresh temps (age floor),
+ * other files' temps, symlinks, and names that only look similar.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { randomUUID, createHash } from 'node:crypto';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ utimesSync,
+ writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { verifyPolicyLedger, withPolicyTransaction } from '../src/services/policy-runtime.js';
+import { policyTrustRoot } from '../src/services/policy-ledger-anchor.js';
+
+const roots: string[] = [];
+
+afterEach(() => {
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function project(): string {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-policy-orphan-temp-'));
+ roots.push(root);
+ mkdirSync(join(root, '.claude-flow'), { recursive: true });
+ return root;
+}
+
+function aged(file: string, contents = 'partial', ageMs = 10 * 60_000): string {
+ writeFileSync(file, contents);
+ const then = (Date.now() - ageMs) / 1000;
+ utimesSync(file, then, then);
+ return file;
+}
+
+const temp = (base: string, pid = 999_999): string => `${base}.${pid}.${randomUUID()}.tmp`;
+
+async function transact(root: string): Promise<void> {
+ await withPolicyTransaction(root, (engine) => engine.setConfiguredMode('legacy'));
+}
+
+describe('#3164 orphaned atomic-write temp files', () => {
+ it('removes aged state.json and ledger-anchors.json temps in the policy directory', async () => {
+ const root = project();
+ await transact(root);
+ const dir = join(root, '.claude-flow', 'policy');
+ const orphans = [
+ aged(join(dir, temp('state.json'))),
+ aged(join(dir, temp('state.json', 1))),
+ aged(join(dir, temp('ledger-anchors.json'))),
+ ];
+
+ await transact(root);
+
+ for (const file of orphans) expect(existsSync(file), file).toBe(false);
+ expect((await verifyPolicyLedger(root)).valid).toBe(true);
+ });
+
+ it('removes aged anchor and mirror temps in the project trust directory', async () => {
+ const root = project();
+ await transact(root);
+ const id = createHash('sha256').update(realpathSync(root)).digest('hex');
+ const trustDir = join(policyTrustRoot(), id);
+ mkdirSync(trustDir, { recursive: true });
+ const orphans = [
+ aged(join(trustDir, temp('state.anchor.json'))),
+ aged(join(trustDir, temp('ledger-anchor-head.json'))),
+ ];
+
+ await transact(root);
+
+ for (const file of orphans) expect(existsSync(file), file).toBe(false);
+ });
+
+ it('keeps fresh temps, unrelated files, look-alikes and symlinks', async () => {
+ const root = project();
+ await transact(root);
+ const dir = join(root, '.claude-flow', 'policy');
+ const target = aged(join(root, 'outside.txt'), 'must survive');
+ const link = join(dir, temp('state.json'));
+ symlinkSync(target, link);
+ const kept = [
+ aged(join(dir, temp('state.json')), 'in flight', 1_000),
+ aged(join(dir, temp('receipts.ledger.jsonl'))),
+ aged(join(dir, temp('other.json'))),
+ aged(join(dir, 'state.json.tmp')),
+ aged(join(dir, 'state.json.123.not-a-uuid.tmp')),
+ aged(join(dir, `state.json.123.${randomUUID()}.tmp.bak`)),
+ aged(join(dir, `xstate.json.123.${randomUUID()}.tmp`)),
+ ];
+
+ await transact(root);
+
+ for (const file of kept) expect(existsSync(file), file).toBe(true);
+ expect(existsSync(link)).toBe(true);
+ expect(existsSync(target)).toBe(true);
+ });
+
+ it('never fails the transaction when the policy directory cannot be listed cleanly', async () => {
+ const root = project();
+ await transact(root);
+ const dir = join(root, '.claude-flow', 'policy');
+ // A directory with a temp-like name cannot be unlinked; it must be skipped.
+ mkdirSync(join(dir, temp('state.json')));
+
+ await expect(transact(root)).resolves.toBeUndefined();
+ expect((await verifyPolicyLedger(root)).valid).toBe(true);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/services/policy-ledger-anchor.ts b/v3/@claude-flow/cli/src/services/policy-ledger-anchor.ts
index 9626871498..bfc0f0ab01 100644
--- a/v3/@claude-flow/cli/src/services/policy-ledger-anchor.ts
+++ b/v3/@claude-flow/cli/src/services/policy-ledger-anchor.ts
@@ -64,10 +64,10 @@ export type AnchorAssessment =
export type AnchorWriter = (file: string, value: unknown) => Promise<void>;
export type StreamingAnchorWriter = (file: string, value: AtomicJsonSource) => Promise<void>;
-const LOG_FILE = 'ledger-anchors.json';
-const MIRROR_FILE = 'ledger-anchor-head.json';
+export const ANCHOR_LOG_FILE = 'ledger-anchors.json';
+export const ANCHOR_MIRROR_FILE = 'ledger-anchor-head.json';
-export const anchorLogPath = (projectRoot: string): string => join(resolve(projectRoot), '.claude-flow', 'policy', LOG_FILE);
+export const anchorLogPath = (projectRoot: string): string => join(resolve(projectRoot), '.claude-flow', 'policy', ANCHOR_LOG_FILE);
/**
* The home directory trust material lives under: $HOME when it is an absolute path, else the account's home. An empty or relative
@@ -100,7 +100,7 @@ export function policyTrustRoot(): string {
function mirrorPath(projectRoot: string): string {
const id = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
- return join(policyTrustRoot(), id, MIRROR_FILE);
+ return join(policyTrustRoot(), id, ANCHOR_MIRROR_FILE);
}
// Duplicated from policy-runtime.ts's RECEIPT_ARCHIVE_FILE rather than
diff --git a/v3/@claude-flow/cli/src/services/policy-runtime.ts b/v3/@claude-flow/cli/src/services/policy-runtime.ts
index 951968b604..2bd6244d43 100644
--- a/v3/@claude-flow/cli/src/services/policy-runtime.ts
+++ b/v3/@claude-flow/cli/src/services/policy-runtime.ts
@@ -38,6 +38,7 @@ import {
openSync,
readFileSync,
readSync,
+ readdirSync,
readlinkSync,
realpathSync,
renameSync,
@@ -49,12 +50,13 @@ import { hostname, userInfo } from 'node:os';
import { syncPolicyProjection } from '../mods/policy-projection.js';
import { ATOMIC_JSON_WRITER, type AtomicJsonSource } from './policy-anchor-log.js';
import { captureArchiveSnapshot, verifyFullPolicyLedger, type ArchiveSnapshot } from './policy-ledger-audit.js';
-import { assessAnchors, policyTrustRoot, recordAnchor, type AnchorEvent, type AnchorEntry } from './policy-ledger-anchor.js';
+import { ANCHOR_LOG_FILE, ANCHOR_MIRROR_FILE, assessAnchors, policyTrustRoot, recordAnchor, type AnchorEvent, type AnchorEntry } from './policy-ledger-anchor.js';
const POLICY_DIR = join('.claude-flow', 'policy');
const POLICY_FILE = 'state.json';
const LOCK_FILE = 'state.lock';
const RECEIPT_ARCHIVE_FILE = 'receipts.ledger.jsonl';
+const STATE_ANCHOR_FILE = 'state.anchor.json';
const LOCK_WAIT_MS = 5_000;
// #3164: without a bound, `state.receipts` grows forever and every
// transaction's verify/clone/serialize cost is O(all receipts ever issued) —
@@ -328,11 +330,45 @@ async function writeJsonAtomic(file: string, value: unknown): Promise<void> {
}
}
+// #3164: a writer killed between creating its temp file and renaming it
+// (SIGKILL from a caller's timeout, OOM) never reaches writeJsonAtomic's
+// cleanup, so a full-size copy of the file stays behind forever (~250 MB each
+// on a mature ledger). Every writer of these files holds the project's
+// state.lock, so while the lock is held no temp file for them can belong to a
+// write in progress. The age floor keeps removal conservative should that
+// invariant ever be broken; a skipped orphan is removed by a later call.
+const ORPHAN_TEMP_MIN_AGE_MS = 60_000;
+const ATOMIC_TEMP = /^(.+)\.\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
+const PROJECT_ATOMIC_FILES = new Set([POLICY_FILE, ANCHOR_LOG_FILE]);
+const TRUST_ATOMIC_FILES = new Set([STATE_ANCHOR_FILE, ANCHOR_MIRROR_FILE]);
+
+function reapOrphanedTemps(dir: string, files: ReadonlySet<string>): void {
+ let names: string[];
+ try { names = readdirSync(dir); } catch { return; }
+ const now = Date.now();
+ for (const name of names) {
+ const match = ATOMIC_TEMP.exec(name);
+ if (!match || !files.has(match[1])) continue;
+ const file = join(dir, name);
+ try {
+ const stat = lstatSync(file);
+ if (!stat.isFile() || now - stat.mtimeMs < ORPHAN_TEMP_MIN_AGE_MS) continue;
+ unlinkSync(file);
+ } catch { /* already gone, or not removable: never fail the caller */ }
+ }
+}
+
+/** Call only while holding the project's state.lock. */
+function reapOrphanedPolicyTemps(projectRoot: string): void {
+ reapOrphanedTemps(paths(projectRoot).dir, PROJECT_ATOMIC_FILES);
+ try { reapOrphanedTemps(dirname(trustPaths(projectRoot).anchor), TRUST_ATOMIC_FILES); } catch { /* no trust dir yet */ }
+}
+
function trustPaths(projectRoot: string): { key: string; anchor: string } {
const trustRoot = policyTrustRoot();
const projectId = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
const dir = join(trustRoot, projectId);
- return { key: join(dir, 'anchor.key'), anchor: join(dir, 'state.anchor.json') };
+ return { key: join(dir, 'anchor.key'), anchor: join(dir, STATE_ANCHOR_FILE) };
}
function trustKey(projectRoot: string, create: boolean): Buffer | undefined {
@@ -508,6 +544,7 @@ export async function withPolicyTransaction<T>(
mkdirDurably(target.dir);
const release = await acquireLock(target.lock);
try {
+ reapOrphanedPolicyTemps(projectRoot);
const loaded = loadPolicyState(projectRoot);
const engine = AgenticPolicyEngine.fromState(loaded, {
signingKey: process.env.CLAUDE_FLOW_POLICY_SIGNING_KEY,
@@ -698,6 +735,7 @@ export async function verifyPolicyLedger(
// strings, receipt arrays or maps. The descriptor pins path replacements.
const release = await acquireLock(target.lock);
try {
+ reapOrphanedPolicyTemps(projectRoot);
const engine = AgenticPolicyEngine.fromState(loadPolicyState(projectRoot), engineOptions);
const outcome = reconcileLedger(projectRoot, engine, options);
if (outcome.persist) {