feat(trigger): HTTP API 支持 options.steer（codex-app 原生 turn/steer）

[deepcoldy]

背景

core-only 公开面（POST /api/trigger + 两条 poll 路由）此前无法使用 codex app-server 的原生 turn/steer：忙时把消息注入当前活跃 turn（而不是串行排队等它结束）的授权（codexAppSteerable）只在飞书 plain-human 入口计算（computeCodexAppSteerable），HTTP 触发路径从不透传。headless 调用方（如 riff core-only）在任务运行中发追问只能排队等当前轮跑完再起下一轮。

契约

POST /api/trigger 的 options 新增 steer?: boolean（默认 false，与 dryRun 互斥）；响应在实际受理（非幂等复用）时回显 steer: true。

• 首轮：opening root 标记为 steerable（codex canSteer 要求 root 与 follow-up head 都显式授权）。
• 运行中追问（worker live）：runner 用 turn/steer 注入活跃 turn；无法注入（无活跃 turn / closing / review·compact turn / 休眠冷启 / 非 codex-app CLI）时静默降级为普通排队 follow-up，受理不因 steer 报错。
• 非 codex-app CLI：no-op，保持既有 type-ahead 队列语义。

结果归因（steer 组）

codex 对合并的 steer 组只产出一条合并 final：runner 给前 N−1 个成员发空的 steer_superseded final，最后一个成员（=最新 triggerId）拿真 final + usage。

• Lark sink：旧行为不变（superseded 只推进 FIFO，不投递）。
• HTTP sink（http_async / http_wait，本 PR 新增）：superseded 成员先 park（内存 fanout 表 + async-trigger store 的 steerParkedBy 后继指针链，仅 http_async 写 durable）；真 final 落盘后把同一份合并正文 fan-out 给组内每个 parked 成员（wait promise resolve / async result completed + recordCompleted，不带 usage——用量只记最新 trigger），并清 idempotentAsyncTurns 收敛项，避免随后优雅退出把已合并轮误判失败。
• daemon 在「superseded pop → 真 final」之间重启：poll 时沿 steerParkedBy 链走到首个终态后继并镜像（completed 镜像正文、failed 镜像终态证据）；链仍 pending 则继续 running。

安全面

不新增公开路由，core-only 仍是 loopback 的「驱动我自己的 turn」面；steer 只授权注入同一租户自己的活跃 turn。R4/R5 的 superseded 守卫从仅 lark 扩到 lark | http_async | http_wait，VC / doc_comment / suppressed / sink 缺失 / 唯一 head 仍一律 ACK=false 拒绝。

测试

• trigger-api：steer 校验 3 例（布尔类型、与 dryRun 互斥、fresh/follow-up 受理）
• trigger-session-turn-idempotency：live/dormant/无 flag plumbing 3 例
• bridge-final-output-retry：R4/R5 守卫矩阵更新（http_wait 不再拒绝）+ http_async / http_wait 全组 fan-out 2 例
• async-trigger-store：park / N 链 / 终态强证据不覆写 / 严格 schema 4 例

设计文档：docs/design/2026-07-30-api-only-core-only-bot-mode.md 增补一节。

🤖 Generated with Claude Code

[deepcoldy]

自动评审结论：设计与实现整体成立，无阻断性问题，有 1 个建议合入前补齐的测试缺口，加 2 处文档/命名小修。以下为初步意见，最终以维护者审阅为准。

建议合入前处理

1. 重启保险的 poll 镜像路径缺少路由级测试

buildAsyncTriggerLookupResponse（src/core/dashboard-ipc-server.ts）中的 steerParkedBy 镜像块承载着「daemon 在 superseded → real-final 之间重启」这一核心承诺，但独立变异验证（整块删除后跑相关测试）下现有测试全部通过——store 原语（followSteerParkedChain 的长链 / 损坏环 / 缺 hop / failed 后继）覆盖充分，但调用方的三个镜像分支没有被钉住：

• completed 后继 → 镜像正文（不带 usage）
• reason === 'turn_terminal' 后继 → 镜像 terminalErrorCode
• 其余 failed 后继 → dispatch_unknown

以及 owner 回退（persisted.ownerLarkAppId ?? cachedLarkAppId）和「链仍 pending 时保持 running」（重启窗口尚未关闭）这两个语义。建议补一条 trigger-result 路由级测试覆盖三态镜像 + 链 pending = running。

2. 公开 API 文档缺 options.steer

docs-site 中英文 api-task-trigger.md 的 options 有效字段表（dryRun / idempotencyKey 均有条目）没有 steer；英文文中两处 "steer" 是 prompt steering 的无关散文。headless 调用方只看公开文档无法发现新契约，建议补上字段行与一小节说明：与 dryRun 互斥、fresh / follow-up 语义、runner 不可注入时 best-effort 静默降级排队、superseded 组成员轮询拿到合并正文且不带 usage。设计文档增补节已写得很完整，公开页对齐即可。

3. 拒绝码字符串语义已过时（零风险改名）

superseded_head_not_plain_lark_steerable_with_successor（src/core/worker-pool.ts）在本 PR 将 http_async / http_wait 纳入合法 sink 后已名不副实。该字符串全仓仅一处使用、只进 worker 日志，改名无风险（如 superseded_head_not_authorized_sink_with_successor）。

可选（不阻塞合入）

• steerFanoutBySession 在组内最后一轮走 turn_terminal 失败时不会被清理（每个异常会话遗留一个小对象，可在 ledger drain / 会话 close 处顺手清）。
• http_wait parked 成员在整组失败时只能等满自己的 wait timeout（wait 模式既有 best-effort 契约，可留作 fast-follow）。
• 两处建议在注释中显式写明的不变量 / 边界：
  • fanOutSteerGroupFinal 只按 sessionId + generation 匹配 park 表，且对任意非 superseded final 都会触发；其正确性依赖「同一 generation 内后续输入只会 steer 入组、不存在旁路独立派发」这一 FIFO 不变量，写明后可防未来误用；
  • steerParkedBy 指向的后继若为 lark turn（盘上无 async 记录），重启链必断，该成员最终由 session closed → failed(no_output) 收敛——失败方向安全，仅「重启窗口 + 真人插话交错」同时命中，可作为已接受边界落注释。

验证情况

• 已 rebase 到评审时最新 master，无冲突，patch-id 与原推逐字一致；tsc 0 错误。
• 相关测试本地全部通过：PR 四个测试文件 200 例，另加 steer / codex-app dispatch / dashboard IPC / async state 等回归共千余例。
• 变异验证：store / validator / trigger-session plumbing / worker-pool fan-out 的新测试在旧实现下均如期变红；唯一删除后不变红的就是上面第 1 点的镜像块。
• PR 头 CI 唯一失败用例 test/turn-reply-ask.test.ts（150ms 真实定时器时序断言）与本 PR 无文件 / 符号交集，本地多次复跑稳定通过，判断为与本 PR 无关的既有时序 flake。