ruvnet/ruflo · error

policy-state-lock-timeout

Error message

policy-state-lock-timeout

What it means

acquireLock gives up after LOCK_WAIT_MS of contended exclusive-create attempts on the policy state lock file; stale locks older than LOCK_STALE_MS are broken automatically, so this signals live contention or an unbreakable lock.

Source

Thrown at v3/@claude-flow/cli/src/services/policy-runtime.ts:63

async function acquireLock(lockPath: string): Promise<() => void> {
  const started = Date.now();
  while (Date.now() - started < LOCK_WAIT_MS) {
    try {
      const fd = openSync(lockPath, 'wx', 0o600);
      writeFileSync(fd, JSON.stringify({ pid: process.pid, acquiredAt: Date.now() }));
      closeSync(fd);
      return () => {
        try { unlinkSync(lockPath); } catch { /* already released */ }
      };
    } catch {
      try {
        if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) unlinkSync(lockPath);
      } catch { /* another process changed the lock */ }
      await sleep(10);
    }
  }
  throw new Error('policy-state-lock-timeout');
}

function writeJsonAtomic(file: string, value: unknown): void {
  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
  renameSync(temporary, file);
}

function trustPaths(projectRoot: string): { key: string; anchor: string } {
  const trustRoot = join(userInfo().homedir, '.config', 'ruflo', 'policy-trust');
  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') };
}

function trustKey(projectRoot: string, create: boolean): Buffer | undefined {
  const { key } = trustPaths(projectRoot);

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Retry acquiring the policy state lock later
2. Find and stop the process holding the policy state lock

Example fix

Retry the policy operation; if the lock timeout persists, check for a stuck policy-state lock holder and restart the runtime.

When it happens

Trigger: Thrown at v3/@claude-flow/cli/src/services/policy-runtime.ts:63 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/069541358e5ef798. Report an issue: GitHub.