把 Codex 故障当作可恢复状态：Hermes Agent 多 worker 开发中的自愈设计

在多 agent 编程系统里，最危险的失败并不总是“代码写错了”。更常见的情况是：worker 已经做完了大半工作，证据文件也落盘了，但最后一步模型调用、认证状态或任务协议出了问题。系统如果只看最后一个进程退出状态，就会把可恢复的运行时故障误判成任务失败。

这正是 Hermes Agent 使用 Codex 参与开发时需要补上的一层能力：不要把 “Codex 调用失败” 直接等同于 “任务失败”。先看本地状态，再决定恢复、补产物，还是明确 block。

问题一：隔离 profile 看不到 Codex 登录态

Hermes 的 profile 机制会为不同 worker 隔离 HOME 和配置。隔离带来可控性，但也带来一个现实问题：主用户在 ~/.codex/auth.json 里已有 ChatGPT/Codex 登录态，worker 运行在自己的 PROFILE_HOME 下时却看不到它。于是 codex exec 或 Hermes 的 openai-codex 路径可能表现为 401、missing bearer、not logged in。

这类问题不应该首先提示用户去找 API token。更合理的 preflight 是：

• 在启动 worker 前执行 HOME="$PROFILE_HOME" codex login status。
• 如果显示 Logged in using ChatGPT，继续任务。
• 如果是 401、missing bearer 或 not logged in，检查 $PROFILE_HOME/.codex/auth.json。
• 如果主用户 ~/.codex/auth.json 存在，自动为 profile 建立 symlink，然后再次检查登录状态。
• 仍失败时才 block，并明确写出“需要重新登录 Codex”，而不是笼统要求 API token。

这个方向和 Hermes Agent 仓库里的公开讨论一致。PR #18555 增加了复用 Codex CLI 认证的兼容模式，可从 CODEX_HOME/auth.json 或 ~/.codex/auth.json 读取运行时凭据。PR #20457 则描述了另一个同类问题：Hermes 自己的 ~/.hermes/auth.json 为空，但 Codex CLI 的 ~/.codex/auth.json 已经有有效登录态，导致运行时解析失败。它的修复思路是从 Codex CLI 凭据中 bootstrap 到 Hermes auth store。

这些案例说明，认证不是一个单点开关，而是 profile、HOME、credential pool、Codex CLI 共享文件之间的状态同步问题。健康检查应当在 worker 启动前做，而不是等任务失败后才让用户猜。

问题二：401 不一定是“没登录”

401 也需要分类。Hermes Agent issue #23670 记录了 preflight compression 在主 provider 为 openai-codex 时暴露 User not found 401，而主任务仍继续运行的情况。这里的问题不是用户工作完全失败，而是辅助压缩调用的 fallback 没覆盖 auth 错误。

另一个更具体的案例是 issue #23896：某些有 residency enforcement 的 ChatGPT workspace 会返回 HTTP 401: Workspace is not authorized in this region。PR #23935 的修复不是重新登录，而是从 Codex OAuth JWT 里提取 chatgpt_data_residency 或 chatgpt_compute_residency，并发送 x-openai-internal-codex-residency header。

所以 watchdog 看到 401 时不能只给一个通用结论。至少要区分：profile 里没有登录态、Hermes auth store 和 Codex CLI auth store 不同步、辅助模型 fallback 缺口、以及 workspace residency header 缺失。不同根因对应完全不同的恢复动作。

问题三：timeout 和 connection error 不应抹掉已经完成的工作

Hermes issue #13834 记录了一个很典型的现象：同一台 macOS、同一网络下，官方 Codex CLI 能工作，但 Hermes 的 openai-codex 路径反复出现 APIConnectionError、APITimeoutError，最后显示 API failed after 3 retries — Connection error。这类问题很容易被误读为“任务失败”。

但在真实的长任务里，timeout 经常发生在后半程：worker 可能已经抓取了 raw evidence、写出了中间 JSON、保存了日志，只是在生成最终 Markdown/HTML 或调用 kanban_complete 前断掉。此时最差的处理方式是盲目重跑全部采集；它浪费时间，也可能覆盖可用证据。

更稳的流程是：

• 先重试 1 到 2 次，并使用指数退避。
• 如果仍失败，检查 acceptance artifacts：raw evidence、日志、MD、HTML、项目状态文件。
• 如果 raw evidence 已经存在，而最终 MD/HTML 缺失，就从已有证据继续生成缺失产物。
• 如果证据不足，再 block，并写清缺哪个文件、下一步命令是什么。

问题四：protocol violation 可能是“完成了但没收尾”

Hermes Kanban 设计里，worker 最终应该调用 kanban_complete 或 kanban_block。当前代码中，hermes_cli/kanban_db.py 明确把“进程 rc=0 退出，但任务仍是 running”视为 protocol violation：worker 可能以普通文本回答了，而没有做终止状态转换。测试 test_detect_crashed_workers_protocol_violation_auto_blocks 也固定了这一行为：干净退出但没有调用 kanban_complete/kanban_block 时，系统会立即 auto-block，避免无限重试。

公开 PR #24388 在这个方向上又推进了一步：当 Kanban worker rc=0 退出但没有终止 kanban tool call 时，保留最终 worker 日志摘要，把 log path、tail、summary evidence 附到 protocol_violation 和 gave_up event 上，并增加回归测试。

这已经比“静默失败”好很多，但还可以再进一步：protocol violation 不应直接等价于 block。它应该先触发 artifact recovery。若最终产物和验收条件已经满足，只是没调用 kanban_complete，watchdog 应该基于本地验证自动 complete；只有产物不够时才 block。

一次具体事故暴露出的恢复缺口

这次 t_52cac9ce 的问题就属于这一类：worker 已经采集了 raw evidence，但后续 Codex API timeout 后进程退出，没有调用 kanban_complete 或 kanban_block，于是任务落入 protocol violation。单看协议，它确实不合格；但单看工作证据，它并不是从零失败。

正确处理顺序应该是：

1. 发现 worker crash 或 protocol violation 后，先检查 acceptance artifacts 是否已经部分或完全生成。
2. 如果 raw evidence 存在而最终 MD/HTML 缺失，从 raw evidence 继续生成缺失产物，不盲目重跑采集。
3. 本地验收：MD/HTML 非空；覆盖任务要求的对象和维度；raw evidence 路径存在；PROJECT_STATE.md 与 PROJECT_STATE.html 已更新。
4. 验收通过后自动 kanban complete。
5. complete 后立即 dispatch 下游 ready tasks。
6. 如果证据不足，才 kanban block，并写清缺什么、下一步命令是什么。

还要处理安装和 worker 环境依赖

Hermes Kanban 的公开 issue #23725 展示了另一类可恢复故障：Hermes 0.13.0 中，Kanban 系统需要的内置 kanban-worker skill 存在于源码树，但 fresh install 或 update 后没有自动安装。结果 worker 报 Unknown skill(s): kanban-worker，连续失败后 auto-block。PR #23884 的方向是让 hermes kanban init 自动安装 bundled skills。

这说明 watchdog 不只要看模型 API。skill 是否存在、profile 是否完整、worker HOME 是否能访问必要凭据，都是任务执行前的健康检查范围。

建议的 watchdog 规则

• 401 Unauthorized：先跑 Codex profile auth repair；检查 profile 的 .codex/auth.json、主用户 Codex CLI auth、Hermes auth store、credential pool 与 residency header。
• timeout / connection error：重试 1 到 2 次，指数退避；如果已有中间产物，走 resume/recover，不从头重跑。
• protocol violation rc=0：不要直接放弃，先检查是否“产物已完成但没调用 complete”。
• blocked task with completed artifacts：自动本地验证；验证通过就 complete。
• no ready tasks because parent blocked：检查 parent 是否可恢复，而不是只报告 blocked。
• 所有恢复动作：写入 state/PROJECT_STATE.md 和 state/PROJECT_STATE.html，让人和后续 worker 都能追踪。

结论

Hermes Agent 的优势是把模型、工具、skills、memory、profiles、Kanban 和 gateway 组合成一个长期运行的 agent 系统。这样的系统不应该用“一次 Codex 调用成功或失败”来定义任务状态。真正可靠的做法是把 runtime failure 和 task failure 分开：先检查 durable artifacts，能恢复就恢复；证据足够就 complete；证据不足才 block，并把下一步写清楚。

这不是让 watchdog 更“乐观”，而是让它更接近工程现实。长任务的真相通常在磁盘上，不只在最后一次 API 返回里。

参考资料

• https://github.com/NousResearch/hermes-agent
• https://github.com/NousResearch/hermes-agent/pull/24182
• https://github.com/NousResearch/hermes-agent/pull/24388
• https://github.com/NousResearch/hermes-agent/issues/23725
• https://github.com/NousResearch/hermes-agent/pull/23884
• https://github.com/NousResearch/hermes-agent/issues/13834
• https://github.com/NousResearch/hermes-agent/issues/23670
• https://github.com/NousResearch/hermes-agent/issues/23896
• https://github.com/NousResearch/hermes-agent/pull/23935
• https://github.com/NousResearch/hermes-agent/pull/18555
• https://github.com/NousResearch/hermes-agent/pull/20457