Cannot adopt worktree at '${worktreePath}': expected branch

Error message

Cannot adopt worktree at '${worktreePath}': expected branch '${exactTaskBranch}', found '${actualBranch ?? 'detached HEAD'}'.

What it means

When adopting an existing worktree for a task that requested an existing branch (taskBranch.kind === 'existing'), findExisting verifies the worktree's current checked-out branch with getCurrentBranchStrict. If it differs from the requested branch — including a detached HEAD — adoption is refused to avoid working against the wrong branch.

Source

Thrown at packages/isolation/src/providers/worktree.ts:684

        await verifyWorktreeOwnership(toWorktreePath(worktreePath), request.canonicalRepoPath);
      } catch (err) {
        getLog().warn(
          {
            worktreePath,
            branchName,
            codebaseId: request.codebaseId,
            canonicalRepoPath: request.canonicalRepoPath,
            err: (err as Error).message,
          },
          'worktree.adoption_refused_cross_checkout'
        );
        throw err;
      }

      if (exactTaskBranch) {
        const actualBranch = await getCurrentBranchStrict(toWorktreePath(worktreePath));
        if (actualBranch !== exactTaskBranch) {
          throw new Error(
            `Cannot adopt worktree at '${worktreePath}': expected branch ` +
              `'${exactTaskBranch}', found '${actualBranch ?? 'detached HEAD'}'.`
          );
        }
      }

      getLog().info({ worktreePath, branchName }, 'worktree_adopted');
      return this.buildAdoptedEnvironment(worktreePath, branchName, request);
    }

    // Exact-branch requests also search Git's registered worktrees because an
    // external tool may have created the checkout at a non-Archon path.
    const exactBranch = isPRIsolationRequest(request) ? request.prBranch : exactTaskBranch;
    if (exactBranch) {
      const existingByBranch = exactTaskBranch
        ? ((await listWorktrees(request.canonicalRepoPath)).find(
            worktree => worktree.branch === exactTaskBranch
          )?.path ?? null)

View on GitHub (pinned to 0773b97458)

Solutions

In the worktree, run `git checkout <expected-branch>` to match the requested task branch, then rerun
If the worktree is stale or wrong, remove it (`git worktree remove <path>`) so Archon creates a fresh one on the correct branch
If the worktree legitimately holds another task's branch, let that task's run finish or choose a different existing branch
Check `git status` / `git log` in the worktree to understand who moved HEAD before discarding anything

Example fix

# before (inside the worktree)
git checkout experimental
# after
git checkout expected-task-branch

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
export async function worktreeBranchMatches(worktreePath: string, expected: string): Promise<boolean> {
  const { stdout } = await execFileAsync('git', ['-C', worktreePath, 'branch', '--show-current']);
  return stdout.trim() === expected;
}

Try / catch

try {
  const env = await provider.create(request);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.includes('Cannot adopt worktree')) {
    // Inspect/reset the worktree, or remove it so a fresh one is created
    const path = msg.match(/at '([^']+)'/)?.[1];
    console.error(`Worktree ${path} is on the wrong branch; checkout the expected branch or remove it.`);
  }
  throw e;
}

Prevention

Don't manually switch branches inside Archon-managed worktrees
Before reusing an existing task branch, check its worktree's current branch
Clean up finished task worktrees so stale checkouts aren't re-adopted
Avoid committing while in detached-HEAD state in shared worktrees

When it happens

Trigger: WorktreeProvider.create with workflowType 'task' and taskBranch {kind:'existing', branch:X} finds an existing worktree at the expected path (or registered by branch), but `git branch --show-current` in that worktree returns Y !== X, or returns empty (detached HEAD).

Common situations: Someone manually checked out a different branch or committed in detached-HEAD state inside the shared worktree; a previous run left the worktree on another branch; a second task reusing the same worktree path expects a different existing branch.

Related errors

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