Checkout ${cwd} matches multiple registered codebases throug

Error message

Checkout ${cwd} matches multiple registered codebases through Git directory ${checkoutIdentity.commonGitDir}: ${paths}. Register this exact checkout or remove the ambiguity.

What it means

findCodebaseForCheckoutResolver resolves a filesystem checkout to a registered codebase using the checkout's Git identity (common git dir). When more than one registered codebase claims the same live checkout identity, resolution is ambiguous and it throws instead of guessing. The message asks the operator to register the exact checkout or remove the duplicate registration.

Source

Thrown at packages/core/src/services/codebase-checkout-resolver.ts:64

  }

  const checkoutIdentity = await deps.getGitCheckoutIdentity(cwd);
  const matches: Codebase[] = [];
  for (const codebase of await deps.listCodebases()) {
    if (codebase.kind === 'folder') continue;
    try {
      const registeredIdentity = await deps.getGitCheckoutIdentity(codebase.default_cwd);
      if (resolve(registeredIdentity.commonGitDir) === resolve(checkoutIdentity.commonGitDir)) {
        matches.push(codebase);
      }
    } catch {
      // A stale registered path cannot own the live checkout identity.
    }
  }

  if (matches.length > 1) {
    const paths = matches.map(codebase => codebase.default_cwd).join(', ');
    throw new Error(
      `Checkout ${cwd} matches multiple registered codebases through Git directory ` +
        `${checkoutIdentity.commonGitDir}: ${paths}. Register this exact checkout or remove the ambiguity.`
    );
  }
  return matches[0] ?? null;
}

View on GitHub (pinned to 0773b97458)

Solutions

Register the exact checkout path being resolved so an exact match wins over identity matching.
Remove or update the duplicate codebase registrations so only one claims that Git directory.
If the duplicates are worktrees, keep only the primary clone registered; worktrees get isolation through worktree resolution, not separate registration.
Re-point the stale default_cwd of one registration to a different checkout.

Example fix

// before: two registrations
registerCodebase({ default_cwd: '/repo' });
registerCodebase({ default_cwd: '/repo/.worktrees/feat' }); // same commonGitDir
// after: one registration; worktrees resolve through it
unregisterCodebase('/repo/.worktrees/feat');
registerCodebase({ default_cwd: '/repo' });

Defensive patterns

Strategy: validation

Validate before calling

// before lookup, de-duplicate registrations sharing one git dir
const seen = new Set();
for (const cb of await listCodebases()) {
  const id = await gitCommonDir(cb.default_cwd);
  if (seen.has(id)) console.warn(`duplicate registration for git dir ${id}: ${cb.default_cwd}`);
  seen.add(id);
}

Try / catch

try {
  const cb = await findCodebaseForCheckoutPath(cwd);
} catch (e) {
  if (e.message.includes('matches multiple registered codebases')) {
    console.error('Remove duplicate registrations or register this exact checkout');
  } else throw e;
}

Prevention

Register the primary clone only; never register its worktrees as separate codebases.
Remove stale registrations when a checkout moves.
Prefer exact-path registration for checkouts you resolve often.

When it happens

Trigger: Two or more registered codebases have default_cwd paths that resolve to checkouts sharing the same commonGitDir (e.g. the main checkout and a linked worktree both registered as separate codebases), and a lookup by checkout path matches both.

Common situations: Registering both the primary repo clone and one of its git worktrees as independent codebases; registering a nested checkout that shares the same .git directory; re-registering a moved checkout under a new path without removing the old entry.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/1e7229728a167dd1. Report an issue: GitHub.