Waitpoint（等待点）¶

Waitpoint 是一个持久的「这件事完了叫我」对象。Agent 登记一个，把一次性凭证交给 Cortex 之外正在跑的东西 ——训练、构建、评测——然后结束自己这一轮。那东西报告时，这个 session 会被带着结果唤醒。

Cortex 不启动、不托管、不接管你的进程。你照原样跑，只是多加一行。

为什么不用轮询¶

定时检查每次触发都是一次完整的 agent turn，而几乎每次都只是发现「还没完」。Waitpoint 等待期间零开销： session 是空闲的，只有真正该发生的那一轮才会发生。

整体形状¶

agent                          你的任务                      Cortex
  │ wait_create(label, intent)
  │──────────────────────────▶ (id + secret)
  │ 结束这一轮
  ⋮                            跑了六小时
  ⋮                            cortex-signal --exit-code $?  ──▶ waitpoint 触发
  ◀───────────────────────────────────────────────────────────── session 被唤醒

登记¶

wait_create 需要 label（这是什么）和 intent（你在等什么、醒来要做什么）。intent 比看上去重要得多：你会在几小时后、一个没有今天任何上下文的新 turn 里读到它，所以要写给陌生人看。

返回 id、secret，以及可直接粘贴的几行命令——不需要你自己拼。

wait_create({
  label: "夜间训练",
  intent: "cluster 上那个 33k 步的 run；落地后把 loss 曲线和 baseline 对比",
})

先登记，再启动任务，这样发信号那一行就能写进同一条命令里。没有任何东西会自己发信号 —— Cortex 不启动也不看守任何进程，回调没接上的等待点就只会一直挂到过期为止。任务如果已经在跑了，用返回里的 attach_to_pid 那一行去守它的 pid。

回调接上之后，结束这一轮。你不该在这里干等。

发信号¶

在跑守护进程的那台机器上：

export CORTEX_SIGNAL_ID=wp_1a2b3c4d5e6f CORTEX_SIGNAL_SECRET=…
python train.py; cortex-signal --exit-code $?

--exit-code 把 $? 同时变成状态和消息，所以接入就是一行。其余都可选：--message 一句话摘要、 --member 说明这是哪个任务、--data @file 或 --data - 附上日志尾巴。

没有 CLI 时用 curl 同理：

curl -sS -XPOST http://127.0.0.1:3001/webhook/signal \
  -H 'content-type: application/json' \
  -d '{"id":"wp_1a2b3c4d5e6f","secret":"…","status":"ok","message":"33,120 steps"}'

要挂到一个已经在跑的进程上，不需要任何功能——等 pid 消失再发信号即可：

(while kill -0 12345 2>/dev/null; do sleep 5; done; cortex-signal --status ok) &

这样拿不到退出码（内核只把它交给父进程），但至少知道它结束了。

在别的机器上¶

守护进程的 webhook 只监听回环，所以 trainer 机器上的任务打不到它。给 wait_create 传 device: "<名字>"，在设备上落一个文件即可——守护进程会顺着设备已经握着的那条连接来取，一个 sweep 周期内（默认 30s）：

python train.py; s=$?; d=~/.cortex/tmp/signals; mkdir -p "$d"
printf '{"id":"wp_1a2b3c4d5e6f","secret":"…","status":"%s","message":"exit=%s"}' \
  "$([ $s -eq 0 ] && echo ok || echo fail)" "$s" > "$d/$$.tmp" && mv "$d/$$.tmp" "$d/$$.json"

先写 .tmp 再 rename——同目录 rename 是原子的，收取方永远不会读到半截文件。设备上不需要装任何东西。 设备离线时文件就在那儿等着。

这个 spool 目录在守护进程本机同样有效；cortex-signal 在守护进程不可达时会自动落到这里，所以重启期间写出的信号不会丢。

别的用法¶

waitpoint 不是「完成通知」，它是一个带地址的唤醒。它对发信号的一方没有任何假设 —— 所以下面这些用法都不需要新功能，是同一个对象换个地方粘一行而已。

当闹钟。 没人规定信号必须来自真实工作：

(sleep 3600; cortex-signal --message "一小时到了，再看一眼队列") &

当监控。 max_signals 设成大于 1，等待点就一直开着，每次汇报都叫醒你：

wait_create({ label: "nightly", intent: "…", max_signals: 24 })

while :; do sleep 1800; cortex-signal --message "$(tail -1 train.log)"; done &

每小时的唤醒上限照常生效，话痨的监控烧不垮这个会话。拿到想要的之后自己 wait_cancel 关掉 —— 什么时候算完，是你的判断，不是服务器的。

不打扰你的心跳。 --status progress 只记录、不结算、不唤醒；你下次去看时才看到它，会话的等待栏里也有。「还活着，第 12000 步」用它，把 ok/fail 留给真正值得一个 turn 的时刻。

两者同时。 让真实任务和一个 sleep 循环打到同一个等待点：谁先到谁叫醒你，而 check-in 会告诉你这个 run 还活着 —— 不用你主动去问。

同时等多个任务¶

写上成员名，waitpoint 就变成一个 barrier：

wait_create({
  label: "T2 阶梯",
  intent: "三个 arm 全部；全到齐时叫我，或者任何一个挂掉时立刻叫我",
  members: ["arm2", "arm6", "arm8"],
})

每个任务用 --member arm2 发信号。默认第一个失败就立刻唤醒（fail_fast），否则等三个都到齐才唤醒一次 ——一轮，而不是三轮。几秒内到达的信号会被合并进同一次唤醒。

--status progress 只记录心跳、不解决也不唤醒，适合想报进度又不想吵醒谁的任务。

触发时你会看到什么¶

一条消息，写明是哪个 waitpoint、等了多久、谁报告了什么，以及你当初写下的 intent。外部载荷会带上，但明确标注为数据——任何持有 secret 的人都能写它，而它是以 user turn 的身份进入你的对话的，所以绝不能当成指令读。

如果到期了还没人报告，你也会收到一条说明。让 agent 对着沉默一直等，比告诉它「什么都没来」更糟。

在 UI 里看¶

等待属于会话，所以它就显示在会话里 —— 没有另开一个要专门去翻的面板。

输入框正上方。 只要这个会话在等东西，输入框上方就有一行： 等 2 个信号 · train-arm2 · 3 小时后过期。点开是全貌：agent 当初写下的 intent、quorum 进度、已经收到的每一条信号（含来源），以及取消按钮。什么都没等的时候它一个像素都不占，普通会话完全照旧。

只显示还在等（armed）的。已经触发或过期的，本来就往会话里投过一条通知，再在面板里留一份等于同一件事讲两遍。

在会话列表里。 正在等外部信号的会话，名字旁边是一个空心环 —— 刻意不用琥珀点：琥珀在整个 Cortex 里只表示「卡在你身上」（待回答的问题、待批的计划）。等机器不需要你做任何事，不该和那个唯一真正要你响应的标记抢注意力。

展开后重点看三件事，每一件都是唤醒会悄无声息失败的方式：

徽标	含义
`已达唤醒上限（12/时）`	限流已经生效。信号仍会被记录，但不再唤醒本会话，而且这个标志置位后永不复位。
`投递重试中 · N 次`	信号到了，唤醒没送达。悬停可看具体错误。
`本小时已唤醒 N/12`	配额快用完了。

发信号用的 secret 不会显示：服务器只存它的哈希，明文在登记时给出一次。UI 只能复制 id，不能复制凭证。

哪些等待点算「这个会话的」，是两条规则取并集：这个会话布下的，或者它的唤醒会投递到这里。后一条才是通知器真正使用的依据，所以同一 channel 上由更早的会话布下的等待点（!new 之后，或计划任务的下一次运行）会显示在真正会收到它的那个会话里。

运维参数¶


默认存活	7 天（`CORTEX_WAITPOINT_TTL_MS`），硬上限 30 天
收取间隔	30s（`CORTEX_WAITPOINT_SWEEP_MS`）
唤醒上限	每个 waitpoint 每小时 12 次（`CORTEX_WAITPOINT_MAX_WAKES_PER_HOUR`）
默认一次性	`max_signals` > 1 变成信箱模式

wait_check 看你在等什么；wait_cancel 撤掉不再关心的——值得顺手做，否则一个被遗忘的 waitpoint 会在几天后就着谁都想不起来的事把你叫醒。

安全¶

secret 是只对一个 waitpoint 生效的能力凭证：它能解决那一个 waitpoint，别的什么都干不了。这正是 signal 路由不走 CORTEX_WEBHOOK_TOKEN 的原因——那把钥匙能在每台已连接设备上执行命令，训练脚本没有理由持有它。

secret 以哈希存储、按常数时间比对、随 waitpoint 一起过期。载荷有大小上限；未知 id 会被限流并记录，这样脚本里打错一个字是查得出来的，而不是悄无声息。