ruvnet/ruflo · error · Error

invalid worktree registry record

Error message

invalid worktree registry record

What it means

After parsing the registry JSON, status() requires record.version === 1, record.runId === the requested run id, and resolve(record.repoRoot) === the coordinator's own repoRoot. Any mismatch means the file is corrupt, was written by an incompatible coordinator version, or belongs to a different repository, and the whole record is rejected as invalid.

Source

Thrown at v3/@claude-flow/codex/src/worktrees/coordinator.ts:104

        assignments,
      };
      this.writeRecord(registryPath, record);
      return record;
    } catch (error) {
      for (const assignment of assignments.reverse()) {
        try { git(this.repoRoot, ['worktree', 'remove', assignment.path]); } catch { /* retain work for recovery */ }
      }
      throw error;
    }
  }

  status(runId: string): WorktreeRunRecord {
    assertId(runId, 'run id');
    const file = this.registryPath(runId);
    if (!existsSync(file)) throw new Error(`unknown worktree run: ${runId}`);
    const record = JSON.parse(readFileSync(file, 'utf8')) as WorktreeRunRecord;
    if (record.version !== 1 || record.runId !== runId || resolve(record.repoRoot) !== this.repoRoot) {
      throw new Error('invalid worktree registry record');
    }
    const expectedPrefix = resolve(join(this.worktreeBase, runId));
    for (const assignment of record.assignments) {
      const actual = resolve(assignment.path);
      if (actual !== expectedPrefix && !actual.startsWith(`${expectedPrefix}/`)) {
        throw new Error(`registry path escapes owned worktree root: ${actual}`);
      }
    }
    return record;
  }

  integrate(runId: string, agentIds?: string[]): { merged: string[] } {
    const record = this.status(runId);
    const wanted = agentIds ? new Set(agentIds) : null;
    const merged: string[] = [];
    for (const assignment of record.assignments) {
      if (assignment.readOnly || (wanted && !wanted.has(assignment.agentId))) continue;
      git(this.repoRoot, ['merge', '--no-ff', '--no-edit', assignment.branch]);

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Delete the stale registry file (and any leftover worktrees under the sibling .ruflo-worktrees directory) and re-prepare the run with the same or a new run id
2. Construct CodexWorktreeCoordinator with the exact git top-level repoRoot that originally created the record
3. Treat registry JSON as internal coordinator state: never hand-edit, commit, or move it between repositories

Example fix

// before
const c = new CodexWorktreeCoordinator('/repo-clone-b');
c.status('run-1'); // throws: invalid worktree registry record (repoRoot mismatch)

// after
const c = new CodexWorktreeCoordinator('/repo-clone-a'); // same root that prepared the run
c.status('run-1');

import { readFileSync, existsSync } from 'node:fs';
function registryLooksValid(file: string, runId: string, repoRoot: string): boolean {
  if (!existsSync(file)) return false;
  try {
    const r = JSON.parse(readFileSync(file, 'utf8'));
    return r.version === 1 && r.runId === runId && resolve(r.repoRoot) === resolve(repoRoot);
  } catch { return false; }
}

try {
  const record = coordinator.status(runId);
} catch (e) {
  if (e instanceof Error && e.message === 'invalid worktree registry record') {
    // registry is corrupt/foreign: clean up this run's files and re-prepare
    // (remove <runId>.json and the run's worktree dir), or start a new run id
  } else throw e;
}

When it happens

Trigger: Hand-editing or truncating <runId>.json; a record written by a coordinator version using a different version field; copying .claude-flow/swarm/worktrees between repos or machines so record.repoRoot no longer matches; renaming the registry file to a different run id than the one stored inside.

Common situations: Upgrading @claude-flow/codex across registry-format changes; accidentally committing the registry directory and sharing it between clones; two coordinator instances constructed with different repoRoot paths.

Related errors

• unknown worktree run: ${runId}
• registry path escapes owned worktree root: ${actual}
• Unsupported GGUF version: ${version} (expected 2 or 3)
• Unsupported KV cache version: ${version}
• Failed to parse RVFA header JSON

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