codex-app-server/docs/thread-wait-ops.md

# 线程等待与状态读取：与 Codex app 的对照

本批实现把 Codex app 的 8 个线程/等待类工具落到本控制面。
原则：只读的绝不写（不重跑、不批准、不合并），等待的绝不
创建任务或发指令；所有“状态”都来自已有记录（任务行、
trace、审批表、后续表、git 目录），没有的字段明说没有，
不编造。

## 三类

| 类 | 官方工具 | 本端点 | 说明 |
|---|---|---|---|
| 管理并行 Agent | wait_threads | POST /tasks/{id}/wait | 等一批线程的首个重要变化 |
| 管理并行 Agent | read_thread | GET /tasks/{id}/thread/read | 深入查看单个线程的摘要 |
| 管理并行 Agent | send_message_to_thread | POST /tasks/{id}/thread/message | 向已授权线程发后续指令 |
| 读取任务状态 | get_handoff_status | GET /tasks/{id}/handoff | 移交到另一主机后的进度 |
| 读取任务状态 | get_worktree_creation_status | GET /tasks/{id}/worktree | worktree 准备状态 |
| 读取任务状态 | read_pull_request_check_diagnostics | GET /tasks/{id}/pr/checks | PR 的 CI 诊断 |
| 持续监控/等待 | automation_update | GET/PATCH /projects/{id}/automations/{aid} | 长期自动化的查看与修改 |
| 持续监控/等待 | clock.sleep | POST /tasks/{id}/sleep，host sleep | 一次性等待后继续 |

配套：POST /tasks/{id}/handoff 与 POST /tasks/{id}/handoff/{hid}/report
是移交的登记与上报口（官方是“先发起 handoff 再轮询”，
本批把发起与上报也补齐，否则 GET 无数据可轮询）。

## 对照表

### wait_threads — POST /tasks/{id}/wait

- 入参：`task_ids`（可选，缺省取锚任务的 coordinator 子任务），
  `timeout_seconds`（缺省 30，上限 120），`after_cursor`（可选）。
- 一次最多 8 个线程，超了回 400（不静默截断）。
- 只返回第一个发生重要变化的线程：完成/失败等终态、
  需要用户输入（elicitation 审批）、需要审批（其它审批）、
  需要继续处理（待后续消息）。变化判断按 task_ids 顺序，
  不是按真实时间戳排序。
- 无变化时超时回当前进度（progress 全量 + timed_out=true）。
- `after_cursor`：上一次返回的 cursor 只含各任务的状态计数，
  不含正文；带它再等时，已报过的变化不再重复报。
- 它不创建任务、不发指令，只等和收集状态。
- 诚实边界：变化检测只读数据库（任务行、审批表、后续表），
  不轮询 trace 文件；跨任务顺序是调用方给的顺序。

### read_thread — GET /tasks/{id}/thread/read

- 返回：状态映射（queued→waiting，completed/merged→completed，
  failed/merge-failed→failed，interrupted→interrupted）、
  线程摘要、最近活动（trace 末 10 条）、改动文件（trace 里
  kind=file 的路径去重，上限 50）、执行命令（kind=exec 的
  命令与退出码，末 20 条）、待审批、待后续、Agent 链、
  阻塞/需要决策/需要处理/需要指令的 attention 汇总。
- 线程取不到时 thread=null + note，仍回 200（与 /thread 的
  409/502 不同：读摘要不该因为线程缺失而全单失败）。
- `test_results` 恒为 null + 说明：trace 里没有独立的测试
  结果记录，测试只能从命令退出码与 Agent 消息里看，不编
  “测试通过”。
- docker 执行器任务没有本机线程，thread=null（这是预期，
  不是故障）。

### send_message_to_thread — POST /tasks/{id}/thread/message

- 入参：`body`（必填，上限 20000 字），`mode`（queued|direct，
  缺省 queued）。
- 授权模型：API 侧要求 API key + 项目 create_task 权限，
  并记审计 thread_message_sent；“用户在聊天里让我协调”
  本身不是 API 权限，调用方必须持 key。
- 排队/运行中任务：写入 task_followups（pending），direct
  模式同时追加一条直接 trace。
- 已完成/失败/中断的任务：不是 409，而是复活——用 CAS
  把状态改回 queued、清空旧结果与旧错误、写入 resume_message；
  若已有待复活消息或状态已变，回 409（不双重复活）。
- 已合并任务回 409：worktree 已删，应 fork 新任务而不是复活。
- 目标任务（goal/verify）回 409：目标任务不接受后续消息。
- 发给其它任务的消息需要用户明确授权；本任务内按用户指令
  协调。跨项目发消息不在本端点（走 peer_messages 的
  /messages，跨项目会被拒绝）。

### get_handoff_status — GET /tasks/{id}/handoff

- 移交状态：pending / accepted / running / completed / failed；
  终态不可再变，同态重报只算进度更新；进度 0–100，不因
  终态强制改成 100。
- 同一任务同一时间只能有一个未关闭移交，否则建移交回 409。
- 响应含 current_host 与 arrived（当前主机是否等于目标主机）：
  这是“到了”的证据。
- 诚实边界：服务端只登记意图与轮询上报，不执行 SSH 迁移、
  不搬文件；实际迁移由目标主机的 worker 执行并回 report。

### get_worktree_creation_status — GET /tasks/{id}/worktree

- 状态：remote（worktree 在别机）/ ready（目录 + .git）/
  present_no_git / creating（排队或运行中且目录未建）/
  missing（终态且目录未建；已合并任务删 worktree 是设计，
  不是丢失）/ unknown。
- 本机且已就绪时附带当前分支（git branch --show-current，
  失败则 null，不阻塞整单）。
- 诚实边界：worktree 创建在本系统是同步的，没有可观测的
  “接收对象 / 更新文件”阶段流，不编百分比。

### read_pull_request_check_diagnostics — GET /tasks/{id}/pr/checks

- 只读：不重跑检查、不批准、不合并。
- 两层取数：`gh pr checks --json`（workflow、link、description
  即哪个 Action 失败与失败摘要），JSON 失败时回落制表符解析；
  有仓库 + head sha 且有失败项时，再走 check-runs API 拿
  失败日志原文（output.text，截 4000 字）与文件行号注释
  （annotations：path / start_line / message，上限 20 条，
  失败 run 上限 5 个）。
- check-runs 一层失败时不 502 整单：checks 本身已够回答
  “哪个检查失败”，此时 check_runs 回 available=False + note。
- 无 PR 时 409；worktree 在别机时 409（gh 必须在 worktree
  所在主机跑；诊断是只读拉取，不排队等对方 worker）。

### automation_update — GET/PATCH /projects/{id}/automations/{aid}

- GET 回定义 + 近期运行（运行取不到时 runs=[] + note，
  不 502 定义本身）。
- PATCH 只接受 name / prompt / interval_seconds / repo_url，
  其它键静默忽略；无可更新字段回 400；已取消的自动化
  回 409（取消是终态，更新不能复活）；同项目同名冲突回 400。
- 更新不重置 last_run_at：改间隔只影响下一次到期，绝不
  触发一次立即运行。
- 诚实边界：“变化才通知”未实现：每次运行终态仍按现有
  worker 推送通道通知，没有“与上次输出比对、无变化静默”
  的抑制逻辑。

### clock.sleep — POST /tasks/{id}/sleep 与 host sleep

- API：read 权限；seconds 缺省 5，只接受 0–60 的数，超出
  回 400（API 层不静默截断）；睡的是调用方的等待，不暂停、
  不加速、不改动任务本身；返回时重读任务状态。
- host：`host.py sleep --seconds N`，0–60，超了退出码 1；
  Ctrl-C 打印已睡秒数 + interrupted=true，退出码 130。

## 10 步协调流程（映射到端点）

1. 主 Agent 明确需求、影响客户端、验收标准
   → 写进 POST /tasks 的 prompt（目标任务用 verify_command）。
2. 为 Android、iOS、macOS、Web 或后端分别派发子任务
   → POST /tasks，parent_task_id 指向主任务（coordinator）。
3. 每个子任务在独立 worktree 或明确分支中开发
   → 任务 worktree 由 worker 分配；GET /tasks/{id}/worktree 查。
4. 使用 wait_threads 等待任务完成或遇到阻塞
   → POST /tasks/{主}/wait（缺省即等 coordinator 子任务）。
5. 使用 read_thread 查看详细结果
   → GET /tasks/{子}/thread/read。
6. 对失败任务使用 send_message_to_thread 要求修复
   → POST /tasks/{子}/thread/message（失败任务会复活续跑）。
7. 汇总各客户端改动并检查共享 API、事件和数据结构
   → 各子任务的 read_thread 摘要 + result_text 人工/主 Agent 对照。
8. 运行跨客户端构建、测试和集成验证
   → 新建验证任务（或目标任务的 verify_command），再走 4–6。
9. 读取 PR 的 CI 诊断并继续修复
   → POST /tasks/{id}/pr 建 PR 后，GET /tasks/{id}/pr/checks，
   失败项用 thread/message 发回修复。
10. 最后由主 Agent 汇总变更、证据和剩余风险
    → 各任务 result_text + trace + 本对照表的诚实边界。

## 派发模板（映射到 POST /tasks 字段）

- 任务：prompt 首行写清任务名与一句话目标。
- 客户端：prompt 内写明（Android / iOS / macOS / Web / 后端），
  本系统没有独立的客户端字段，不要另建字段。
- 仓库：项目 repo_url（建项目时定）；子任务不另设仓库。
- 基线提交：写进 prompt（如“基线 abc123”），或 environment
  的分支字段；没有独立的基线字段。
- 要求：写进 prompt（复用现有组件、不新建导航页等约束）。
- 验收：写进 prompt；目标任务另用 verify_command 做自动验收。
- 返回：任务完成时 result_text + trace；read_thread 再给出
  改动文件、命令与退出码、待处理项。主 Agent 按“改动文件 /
  执行命令与结果 / 未解决问题”三项核对，不只看一句“已做完”。

## 未实现 / 未宣称

- worktree 创建阶段流（接收对象、更新文件百分比）：无。
- automation 的“无变化静默”抑制：无。
- 测试结果独立记录：无（只有命令退出码与 Agent 消息）。
- handoff 的实际迁移执行：服务端不做，靠目标主机 worker 上报。
- wait 的 trace 级变化检测：无，只有数据库级变化。
- 自动注入身份/记忆上下文到任务：不在本批（见 identity-memory）。