运行失败：Failed to authenticate: OAuth session expired and could not be refreshed |
runtime 在线不代表 agent CLI 能用：那台机器上 Claude Code 等的订阅登录过期了，到机器上重新登录。autoteam doctor 会报出每个 agent 最近一次失败的原因；修好之前可以先在 registry.yaml 里把 agent 挪到别的 runtime |
运行失败：You've hit your session limit · resets 1:10am |
订阅的窗口额度用完了。平台不会自动重试额度类错误，任务停在原状态；Planner 下一次巡检会重新派发（额度恢复后也可以手动触发“推进巡检”）。同一个订阅账号下的所有 agent 共用额度，registry.yaml 里要如实写 account；额度经常不够，就加一个其他厂商或按量计费的 agent 分担 |
| 批准了任务，Planner 没反应 |
确认任务指派给 Planner，且确实从 backlog 改成 todo；用 multica issue runs <任务> 看是否生成运行。--no-start 会抑制启动，本工作区还观察到界面改状态后未生成运行的实例，见唤醒规则。有运行但未执行时检查 autoteam runtimes |
| Planner 派发了，Implementer 没开始 |
runtime 离线或并发满了（任务在排队，排队超过 2 小时会失败）；或者 agent 是 private，而触发链路上的人不是 agent 的创建者：把 AUTOTEAM_AGENT_ACCESS 改成 workspace 后 autoteam multica --apply --only agents |
| Reviewer 没被叫醒 |
评论里只写了 @名字，没用提及链接 [@名字](mention://agent/<UUID>)；或者用了 /note |
| 改了状态为什么没人被叫醒 |
Multica 0.5 起，自定义状态不再负责唤醒；0.5.1 起还可为任务单独设置事件或定时唤醒，见唤醒规则 |
Can not approve your own pull request |
Implementer 和 Reviewer 是同一个身份：两个 AUTOTEAM_*_APP_ID 配成了一个，或者还没建 App。建两个 App；在此之前用试用模式（Reviewer 会改用【批准】评论评审） |
| PR 刚开就被合并了，没经过评审 |
没有平台闸门的仓库里执行了 gh pr merge --auto，它会立即合并。确认 Implementer 的指令是最新的（先跑 merge-mode.sh，输出 reviewer 时不合并）；根本的解决是让规则集生效 |
| 检查一通过 PR 就被合并，Reviewer 来不及看 |
规则集的必需检查生效了，但审批数是 0（单身份只能这样），平台看没有别的条件就合并了。merge-mode.sh 认出这种情况会输出 staged，Implementer 应该开 draft PR——draft 不能开自动合并，要等 Reviewer gh pr ready 才放行 |
Cannot use -d or --delete-branch when merge queue enabled |
有合并队列时 gh pr merge 不接受 --delete-branch：分支由仓库设置 delete_branch_on_merge 自动删（autoteam github --apply 会打开它），命令里去掉这个参数就行 |
The merge strategy for main is set by the merge queue |
这不是报错：PR 已经进了合并队列，平台会在临时分支上用最新主干重跑一遍检查再合并，gh pr view <PR> --json state 等它变成 MERGED |
开了合并队列后 mergeStateStatus 一直是 BLOCKED |
有合并队列时这是常态，不代表缺审批：直接合并本来就被禁止，只能走队列。看 reviewDecision 和 gh pr checks 判断审批和检查，看 state 判断有没有合并 |
New changes require approval from someone other than X because they were the last pusher |
规则集的 require_last_push_approval：最后一次推送的人不能当批准人。agent 流程里不会遇到（Implementer 推、Reviewer 批）。人改规则文件时会撞上——.autoteam/ 受 CODEOWNERS 保护只有人能批，而人又是推送者。用 autoteam propose --apply 让 Implementer App 身份推这个分支并开 PR，人只负责批准；注意 GitHub 更新“最后推送者”有延迟，换完身份等几分钟再重试。换身份推送要先清空凭据助手，否则系统钥匙串里的凭据优先：
git -c credential.helper= -c credential.helper='!f() { echo username=x-access-token; echo password=$BOT_TOKEN; }; f' push |
| PR 迟迟不合并 |
检查没过、审批数不够、CODEOWNERS 要求你批准（改了规则文件）、或者没开自动合并。gh pr view <PR> --json mergeStateStatus,autoMergeRequest,reviewDecision |
| PR 合并后任务直接变成 done 了 |
PR 正文写了 Closes XXX-123 之类的关闭关键字，Multica 的 GitHub 集成会直接设为完成。只在标题写任务编号 |
| 运行失败后任务回到了 todo 而不是 in_progress |
平台的失败回滚只写内置状态，Planner 巡检时会处理 |
| 部署了但 Planner 没验收 |
看 deploy.yml 的 notify planner 步骤；“部署结果”是 run_only，Planner 的 runtime 离线时会跳过，巡检会补查超过 1 小时的待上线任务 |
| autopilot 自己停了 |
过去 7 天至少 50 次运行、失败率 90% 时平台会自动暂停，看运行历史里的报错 |
| agent 说“验证通过”但其实没跑 |
指令要求贴输出；不贴的在评审里打回。规律性出现就在 AGENTS.md 里补规则（带原因） |
| 同一个任务来回打转 |
.autoteam/scripts/loop-guard.sh <任务> 看次数；到上限 Planner 会升级给你 |