Archon 提示 worktree 属于另一个 clone 怎么排查？

Archon 提示 worktree 属于另一个 clone 怎么排查？

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

当你在某个本地 clone 里执行 workflow（尤其是带--branch <name>的运行）时，Archon 没有启动任务，而是抛出一条关于 worktree 归属的报错。最常见的现象是：

Worktree at <path> belongs to a different clone (<other-clone-path>). Remove it from that clone or use a different codebase registration.

它和下面几条报错出自同一套隔离（isolation）系统，本文按"识别报错 → 理解根因 → 选定一条修复路径 → 验证"的顺序排查。适用前提是：你对同一个远端仓库（同一个owner/repo）存在两个或更多本地 clone，并且其中某个 clone 已经为某次运行创建过 worktree。

先确认是哪一条报错

这些报错都出现在从某一个 clone 启动 workflow 时。原文给出的四类提示分别是：

Worktree at <path> belongs to a different clone (<other-clone-path>). Remove it from that clone or use a different codebase registration. Cannot verify worktree ownership at <path>: <reason> Cannot adopt <path>: path contains a full git checkout, not a worktree. Cannot adopt <path>: .git pointer is not a git-worktree reference.

第一条是典型的"跨 clone 冲突"；后三条是它的变体，各自对应略不同的子原因（见文末"其它报错变体"）。<path>、<other-clone-path>是报错里给出的具体路径，<reason>是具体的失败原因，后续命令中的同名占位符都要替换成报错里的实际值。

为什么会跨 clone 冲突

Archon 用远端 URL（owner/repo）来推导 codebase 身份，因此同一远端的两个本地 clone 共享同一个codebase_id。所有 worktree 都存放在一个共享路径下：

~/.archon/workspaces/<owner>/<repo>/worktrees/

也就是说，clone A 创建出来的 worktree，在磁盘上从 clone B 也能看到。隔离系统拒绝"静默接管"另一个 clone 的 worktree，因为那样会操作到错误的文件系统状态——这正是报错要拦下来的地方。理解了这一点，就能明白为什么解决思路是"让两个 clone 不再争抢同一个 worktree 路径"。

排查与解决（三选一）

下面的命令都要在报错所指向的那个 clone 之外——也就是先确认冲突 worktree 究竟属于哪个 clone，再到那个 clone 的目录里操作。

方案一：移除另一个 clone 的 worktree

如果你已经不需要另一个 clone 里那项未完成的 worktree，把它清掉。先列出当前所有活跃 worktree，确认分支名和路径：

archon isolation list

该命令按 codebase 分组，显示分支名、路径、创建时间与状态。确认无误后，二选一：

# 优雅清理：移除该分支的 worktree、本地分支和远端分支 archon complete <branch-name> # 或者，当确实没有需要保留的工作时，直接用 git 强制删除 git worktree remove <path> --force

• <branch-name>用archon isolation list里显示的分支名替换；<path>用报错或 list 里给出的 worktree 路径替换。
• archon complete会删除 worktree、本地分支和远端分支，并把该隔离环境标记为已销毁；它默认会在确认补丁已在远端默认分支上之后才移除，--force可跳过安全检查。因此如果该 worktree 还有未合并的提交，先想清楚是否要丢弃。
• git worktree remove <path> --force会直接删除该 worktree 目录，未提交的改动会被丢弃，不可恢复。仅在确认没有需要保留的内容时使用。

方案二：本次运行改用另一个分支名

让这次运行不和其它 clone 争抢同一路径，换用一个新的分支名即可：

archon workflow run <name> --branch <different-name> "task"

<name>是 workflow 名，<different-name>是一个另一个 clone 没在用的新分支名，"task"是任务描述。分支名唯一对应一个 worktree，换名字就能绕开冲突，且不动另一个 clone 的任何状态。

方案三：固定只用一个 clone

如果两个本地 checkout 本来就是同一个项目，最彻底的办法是收敛到一个 clone。需要说明的是，Archon 的 codebase 注册目前假设"每个远端对应一个本地路径"，真正的多 clone 支持尚未提供（文档中作为一个未完成的跟踪项记录）。因此当两个 clone 长期并存时，方案三是结构性修法。

其它报错变体怎么判断

如果命中的不是"belongs to a different clone"，而是下面几条，按各自的现象处理：

• Cannot adopt <path>: path contains a full git checkout, not a worktree.说明在 worktree 路径上有一个非 Archon 创建的完整 git 仓库。移除或挪走这个目录即可。
• Cannot adopt <path>: .git pointer is not a git-worktree reference.说明该路径下的.git文件指向了意料之外的位置（比如是子模块或格式损坏）。用下面命令查看它实际指向哪里，再手动清理：

  cat <path>/.git

• Cannot verify worktree ownership at <path>: <reason>说明读取<path>/.git时遇到文件系统权限或 I/O 错误。检查该路径与~/.archon/workspaces的权限：

  ls -la <path>

怎么确认已解决

修复动作完成后，重新执行之前那条archon workflow run命令作为验证：如果它不再抛出 worktree 归属错误、并能在~/.archon/workspaces/<owner>/<repo>/worktrees/下创建出本次运行对应的 worktree，就说明两个 clone 已不再争抢同一路径。再跑一次archon isolation list，确认列表里没有来自另一个 clone 的冲突条目，本次运行就能正常进行。

需要记住的边界是：每个分支名只对应一个 worktree，不要在同一分支上同时启动两次运行；而"同一远端多个本地 clone"本身目前不被支持，长期共存时建议按方案三收敛到一个 clone。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon