watch-and-act

用途

watch-and-act 用于处理一类特定场景：当前运行需要等待一个「外部信号」，而运行环境本身无法在信号变化时通知你。典型信号包括 CI 流水线状态、部署进度、队列深度、某个端点的健康状态等。它要解决的问题是，如何在不浪费缓存与 token、也不让运行挂死的前提下，合理地等待并响应这些状态变化。

在动手之前，它要求先确认三件事：该信号是否由运行环境自身跟踪（若是自己启动的后台 Agent/Task/Workflow，完成时会被重新唤起，不该轮询）；该信号是否此刻已经解决（若是，直接检查一次即可，跳过循环）；以及等待的是什么转变、每种结果（成功/失败/就绪/超时）分别要做什么。

主要能力

节奏控制：轮询间隔要与信号变化速度以及约 5 分钟的缓存窗口匹配。活跃观察分钟级信号用 60–270 秒（留在缓存内）；空闲、慢速变化或长回退心跳用 1200–1800 秒以上；避免约 300 秒这一最差区间。
时间上限：必须设定截止时间或最大轮询次数，绝不无限轮询。可用轮询次数 = 截止时间 / 间隔，若次数过多说明间隔过短，应放宽。
唤醒机制选择：优先使用原生的等待/监控能力；其次是跨回合调度（如 ScheduleWakeup 或 /loop）；若完全没有唤醒能力，则绝不死等，而是持久化观察状态、输出可恢复的 PENDING 报告。
持久化约束：跨回合轮询时，用 scripts/watch-state.mjs 把截止时间与轮询计数以原子方式写入磁盘。新的唤起是一个全新进程，没有关于起点和轮询次数的记忆，只有绝对截止时间与计数在磁盘上并被每轮读取、递增，停止条件才会如实触发。
结果分类与行动：每轮读取真实状态并记录，通过 next 判断为达到目标 / 仍待处理 / 终态失败 / 超时 / 轮询用尽，并据此执行后续动作、调度下一次、诊断升级或停止报告。终态是持久的，init/observe 会拒绝对已终态的观察重新打开。

使用方式

脚本为 scripts/watch-state.mjs（简称 $WS），有以下子命令：

init：首个周期使用，要求提供外部目标、绝对未来截止时间、轮询上限和有效间隔。会拒绝由环境跟踪的工作（--harness-tracked 总是报错）以及约 300 秒的死区间隔。
observe：每个周期执行一次真实观察，原子计数，终态无法被静默重启。
next：根据持久化状态决定下一步。--wake 反映实际拥有的能力，可为 schedule / native / none（默认 none）；为 none 时返回可恢复的 PENDING 报告，绝不阻塞。
status：只读导出。

示例命令：

WS=watch-and-act/scripts/watch-state.mjs
node "$WS" init .ulpi/runs/ci-watch.json --target "CI on feat-x" \
  --deadline 2026-07-10T12:00:00Z --max-polls 20 --interval 120
node "$WS" observe .ulpi/runs/ci-watch.json --state pending --evidence "queued"
node "$WS" next .ulpi/runs/ci-watch.json --wake schedule

每个周期：用真实命令检查信号（如 gh run list / gh pr checks、curl 健康检查、队列深度查询），读取实际状态并用 observe 记录；用 next 分类；按 next 报告的动作执行——达到目标则 proceed 并停止，仍待处理且有唤醒能力则按 intervalSec 调度下一次，仍待处理但无唤醒能力则输出 PENDING 报告并停止当前回合，终态失败则诊断或升级，超时或轮询用尽则如实报告未达成。

在 Claude Code 上，一次 watch 就是一个 /loop：interval 用上述节奏，停止条件为截止时间/目标。若 watch 需要为一个更大目标把关，可搭配 /goal，让独立验证者确认转变确实发生。当原生 Monitor/等待能力可以阻塞并重新进入时优先使用它。

适用场景

等待外部 CI 结果再决定后续动作。
等待部署完成。
等待某个外部队列或端点就绪。
需要一次性的有限等待，而非常驻循环（常驻检查可改用 schedule-recurring-agent）。
当红色信号属于自己可修复范围时，可衔接 converge-loop 做有界的诊断修复循环。

限制与注意事项

绝不观察由运行环境跟踪的后台工作，只观察真正外部的信号。
绝不无界轮询，必须声明截止时间或最大轮询次数。
绝不选用约 300 秒的间隔。
绝不假设信号状态，每轮读取真实状态。
终态失败要升级，而不是继续轮询期待自愈。
跨回合的上限不能只存在上下文里，必须持久化并每轮读取递增。
无唤醒能力时不要永久阻塞回合，应降级为可恢复的 PENDING 报告。
不要重新打开已终态的观察。

输出契约

报告应包含：所观察的信号（并确认其为外部信号）、使用的唤醒机制（原生监控 / 跨回合调度 / 无→可恢复 PENDING）及跨回合时的持久化状态文件、采用的节奏与理由以及上限、观察到的转变与采取的行动、总等待时间或轮询次数与最终状态。