docs: 节点存活判据 —— 看产物推进,不看进程数/started 行 - #812
Conversation
起因是 TM汇报牛 连续两次 600s 超时。诊断时发现:现场能拿到的信号里大多数 都不能回答「它是不是活着」——进程在、session 在、日志有 started、 lifecycle_state=active、send_task 返回 ok,这些全都可以在节点一个任务都处理不了时成立。 把当时用上的判据写下来,重点是两条: - 存活 = 最近有没有**产出**(hub 上 actor==该节点的新 task_events;桥日志里 出现过 processTask returned 而不只是 queued); - 桥活着 ≠ 运行时活着。TM汇报牛 的实际形态是桥连跑 9.5 天、codex app-server 不存在, 判据是结构性对照:21 个 -桥 里 19 个有对应 -appsrv,缺的只有它和一个 本就不需要 app-server 的 opencode 节点。 附只读排查三步,并写明 tmux -t 要用 = 精确匹配、以及「起回 app-server」 与「重启桥」是两件事(后者丢 threadId 且解决不了前者)。
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 52b8961005
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. **Hub 上的新回执** —— 最近一次 `task_events` 里 `actor == 该节点` 的记录。 | ||
| 这条最强:它跨 vantage 成立(不需要 SSH 到那台机器),而且伪造不了 —— | ||
| 要写进去就得真的走完一轮。 |
There was a problem hiding this comment.
When the bridge receives a task but its app-server is unavailable, processTask calls reportStatus("working") before invoking the runtime, and the server immediately records a running task event with the node alias as actor. Thus the exact dead-runtime scenario described below can still produce a fresh matching event without completing any turn, so this “strongest” criterion can incorrectly prevent recovery; require attributable runtime evidence such as consumed_at or a successful terminal result instead of any actor match.
Useful? React with 👍 / 👎.
| 2. **桥日志里出现过 `processTask returned`**(而不只是 `queued`)。 | ||
| 注意区分:`queued (a turn is in flight)` 说明它**根本没开始**,那不是产出。 |
There was a problem hiding this comment.
A processTask returned line is emitted for failed outcomes as well as successful runtime output. In fact, the missing-app-server example on lines 41–42 produces exactly this line for the 600-second queue timeout, so applying this criterion would classify the document's dead runtime as alive; the check must distinguish successful or activity-backed returns from timeout/error returns.
Useful? React with 👍 / 👎.
| 3. **`sessions.updated_at` 的差分**:同机多个节点一起看,三个在动、一个冻住, | ||
| 才说明是那一个的问题;全都冻住通常是通信层断了,不是节点死。 |
There was a problem hiding this comment.
For an agent-node whose bridge is alive but app-server is missing, sessions.updated_at still advances because the bridge sends reportStatus("idle") every three minutes; dispatching a task also updates the target session timestamp from the server side. Consequently all nodes on the host can show moving timestamps while one downstream runtime is dead, so this differential only diagnoses bridge/Hub connectivity and cannot serve as the claimed node-output liveness signal.
Useful? React with 👍 / 👎.
| ps -eo pid,etimes,args --no-headers | grep -F '<节点配置路径>' | grep -v grep | ||
|
|
||
| # 2. app-server 在不在 —— 用结构性对照,不是看单个节点 | ||
| tmux list-panes -a -F '#{session_name}|#{pane_current_command}' | grep -E '桥$|appsrv' |
There was a problem hiding this comment.
With the requested format, each row is <session_name>|<pane_current_command>, so a live bridge is rendered like <name>-桥|node and does not match 桥$. The pipeline therefore removes every bridge row while retaining appsrv rows, making the prescribed bridge-to-app-server structural comparison impossible precisely when diagnosing a missing app-server; match 桥\| or format/filter the session name separately.
Useful? React with 👍 / 👎.
| 三步都是只读的。**看完再决定动不动**,而且「起回缺失的 app-server」和 | ||
| 「重启桥」是两件事 —— 后者会丢 threadId,而且解决不了前者。 |
There was a problem hiding this comment.
For managed Codex copresence, the app-server is created by anet node start <alias> --copresence using a generated one-time credential file, dynamic port, and newly persisted thread; the repository exposes no supported command that merely “起回缺失的 app-server.” Conversely, restarting only the bridge reads codexThreadId from config.json and resumes it, so it does not inherently lose that ID. Replace this unsupported dichotomy with the existing full-three-piece SOP or add an authoritative isolated launcher before recommending that action.
AGENTS.md reference: AGENTS.md:L23-L23
Useful? React with 👍 / 👎.
拿独审在 #805 上用的口径审自己这份 docs,三条排查命令**全部有问题**, 逐条实测坐实: 1) `grep -F '<节点配置路径>'` —— 又是占位符。照抄命中 0 条, 而这一步是判「桥在不在」,零命中会被读成「桥没跑」。 改成先 `node=<名字>` 再引用,并写明「不要把占位符原样敲进命令行」。 2) `grep -E '桥$|appsrv'` —— **一个桥都匹配不到。** 输出格式是 `会话名|命令`,行尾是**命令**(如 `TM汇报牛-桥|bash`), 所以 `桥$` 永远不命中。本机实测:原写法 20 行,正确写法 `桥\||appsrv` 41 行。**照抄这条得不出这份文档在教的那个桥/appsrv 对照。** 3) `capture-pane -t '=名字-桥'` —— 实测报 `can't find pane`, 我当初诊断 TM汇报牛 时就踩过这个,只是没把教训写进命令里。 要带窗口索引:`-t '=名字-桥:0'` 才可用。 三条修完都在本机真跑过:进程命中 1 条、对照 41 行、capture-pane 可用。 教训同 #805:**写排查步骤的文档,命令自己得先跑通。** 占位符这一类尤其危险 —— 它不会报错,只会安静地给出错误结论。
三条 P1 我逐条验了,全部成立。本 PR 的三条判据都是错的,已转回 Draft。自动审查在 判据 1「Hub 上的新回执 ——
|
五条 P1 裁定完毕:4 条成立,1 条已在当前 head 修掉④「
|
| P1 | 裁定 |
|---|---|
① task_events actor 匹配 = 最强证据 |
错 — working 在运行时之前上报 |
② processTask returned = 活着 |
错 — 超时也打,被本文自己的例子推翻 |
③ sessions.updated_at 差分 |
错 — 3 分钟 idle 心跳推进,与运行时无关 |
④ 桥| 匹配 |
已修,当前 head 无此问题 |
| ⑤ 恢复路径二分 | 错 — 丢 threadId 是假的;"只起 app-server"无此命令 |
三条判据 + 恢复建议,全部需要重写。已转 Draft(上一条),这里补完裁定。
重写时的方向:
- 判据必须用可归因到运行时的证据 ——
consumed_at、带真实产出的终止结果; - 区分成功返回与超时/错误返回;
- 区分运行时写的记录与桥在调用运行时之前写的记录;
- 恢复段先确认仓里实际存在的命令,再写建议 —— 这次就是没确认。
替代判据找到了 —— 而且它早就存在:#520 的两级运行时证据上一条我判「三条判据全错、需整篇重写」,但只给了方向没给判据,那等于把问题留在原地。去找了「只有运行时才写得出来的信号」,结果是这套东西已经建好了,我写文档时没用它。
|
| 判据 | 含义 | 强度 |
|---|---|---|
tasks.consumed_at 有值且新 |
运行时真的开工了(turn-start / 首个活动事件回流) | 最强,可跨 vantage |
tasks.runtime_submitted_at 有值但 consumed_at 为空且已久 |
桥交出去了,运行时没接 —— 正是「桥活着、app-server 死了」的精确指纹 | 强,且能定位故障层 |
桥日志 processTask returned |
不可用:超时也打这行 | 弃用 |
task_events.actor 匹配 |
不可用:reportStatus("working") 在运行时之前就写 |
弃用 |
sessions.updated_at 差分 |
不可用:3 分钟 idle 心跳推进 | 弃用 |
第二行值得单独说:它不只是「能不能判活」,而是能把故障定位到哪一层 —— 而这正是我原文那个「桥活着 ≠ 运行时活着」的例子想说、却没有工具去说的事。
一处我自己刚犯的错,同轮抓到
找写入点时我先 grep SET\s*consumed_at,得到 0 命中,于是差点写下「consumed_at 只有列、没有人写,所以审查建议的方向不可用」。
错了。 那条 SQL 是多行的,consumed_at = COALESCE(…) 单独占一行(:1045),不匹配我的形状。读上下文才看见。
这跟我在 #815 补的那条(查询没覆盖目标 → 得到一个语法正确、语义为空的 0)是同一件事,这次是形状假设:我假设了 SQL 会写在一行里。
顺带更正上一条
上一条我说「按审查建议改用 consumed_at」时,没有验证这个字段是否可用就接受了方向。事实是它可用(而且比建议的更完整,还有 runtime_submitted_at 这一级)—— 但我当时不知道,只是照单全收。
接受一条建议和验证它是两件事。 这次运气好,建议是对的;但我给出的「已接受」在当时是没有根据的。
下一步:按上表重写全文,并给每条判据标注它不能证明什么。冻结中,待收口。
更正我上一条的草案判据:第二行会把一整条运行时通道上的健康节点误判为「运行时已死」上一条我提了这个:
这条不成立。 我按自己反复说的「验前提」去查「车队侧到底有没有人发这个证据」,查出来的结果同时否掉了它。 先说好消息:证据确实在发
所以 但有一条通道按设计永远不报 consumed
在这条通道上,一个完全健康的节点也会永远是 按我那条草案去判,codex 直连 stdio 通道上的每一个正常节点都会被判成「运行时已死」。 修正后的判据
结论: 这与我这两天反复查的那类是同一个形态:同一个信号,正向和反向的证明力不对称。(#825 上那条「加锚对正断言是收紧、对负断言是放松」是同一件事的另一个例子。) 这次的价值在于它被拦在文档之前我上一条把那个"指纹"写得很有把握。如果直接写进文档,它会成为一条看起来比原来三条都严谨、但会造成误判并可能触发不必要重启的指引 —— 而原来那三条至少只是漏报。 拦住它的不是灵感,是那句「谁在调用它」。验前提这一步,这次是在我自己刚提出的判据上做的。 |
第一版给的三条(task_events.actor 匹配、桥日志 processTask returned、
sessions.updated_at 差分)全部是「桥还活着」就会满足的信号:
- actor 事件在 reportStatus("working") 时就写,早于任何运行时调用;
- processTask returned 超时也会打 —— 被本文档自己举的死亡实例推翻;
- updated_at 由 3 分钟一次的 idle 心跳推进。
这份文档的立意是「别看进程数,看产物推进」,而第一版选的三个"产物"
没有一个是产物。根因是写的时候没回到源码确认:每条信号是谁写的、
什么时候写的。
改用 #520 的 tasks.consumed_at。它满足这份文档需要的两个性质,
源码注释里写得很清楚:
Merely fetching/acking an inbox row sets neither.
Node identity comes exclusively from the ntok; callers cannot
self-report an alias or node_id.
但只在正方向可信:codex 直连 stdio 通道按设计永不报 consumed
(见 evidence?.submitted() 上方注释),而通道信息 hub 侧看不到
(由本地 env ANET_CODEX_STDIO_DIRECT 决定,服务端零感知)。
所以「consumed_at 为空」现在不能当故障证据 —— 误判方向是把健康
节点判成已死,而下一步动作通常是重启。负向判据跟踪 #832。
同时修正第一版两处错误的操作指引:
- 「重启桥会丢 threadId」是假的,codexThreadId 持久化在 config.json,
重启会读回并 resume;
- 「起回缺失的 app-server」没有对应命令,它是三件套的一部分。
全文引用改为钉符号不钉行号(#831:文档站 141 处行号引用里,判据能判
的 74 处有 72 处已漂)。七个符号锚点均已验证可 grep 到。
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aab7a111d5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| > 🔴 **`consumed_at` 只在正方向可信。** | ||
| > **有值且新** → 运行时确实开工了,可跨 vantage,不需要 SSH。 | ||
| > **为空** → **不能推出任何结论**,原因见下一节。 |
There was a problem hiding this comment.
When a consumed task is immediately reassigned, reassign_task changes to_name/to_node_id but deliberately preserves consumed_at (confirmed by server/src/task-consumption.test.ts's “reassign preserves task-lifetime evidence” test). The timestamp can therefore be both present and fresh even though it was produced by the previous node and the newly assigned node has never started the task, so this rule can falsely classify that node as working and suppress recovery. Treat consumed_at only as evidence that the logical task was consumed at least once, or pair it with delivery-attempt/consumer identity before using it for node liveness.
Useful? React with 👍 / 👎.
| **跟踪:[#832](https://github.com/sleep2agi/agent-network/issues/832)** —— 在节点自报 | ||
| 「本通道是否发 consumed 级证据」之前,负向判据无法从 hub 侧给出。 |
There was a problem hiding this comment.
Channel capability is not the only reason a healthy task can retain consumed_at = NULL: createTaskRuntimeEvidenceReporter records an evidence level as attempted before starting its non-blocking Hub call, and on an old Hub or transient reporting failure it only logs the error and never retries; the PostgreSQL backend also rejects these evidence writes. Consequently, even after #832 reports that a lane supports consumed-level evidence, a null value still cannot become a negative liveness signal unless successful delivery and backend support are also established.
Useful? React with 👍 / 👎.
| 第一句正是上表所有信号缺的:取任务、ack、回状态都点不亮它。 | ||
| 第二句意味着它**伪造不了** —— 身份只来自 ntok。 |
There was a problem hiding this comment.
The ntok check makes the node identity non-self-selectable, but it does not attest that a vendor runtime emitted an event: any process holding that node token can invoke the registered mark_tasks_consumed MCP tool with an owned task ID, and markTaskRuntimeEvidence verifies only token-bound ownership before stamping the row. A compromised or buggy bridge can therefore manufacture this signal for its own tasks, so the document should distinguish trustworthy attribution from proof that cannot be forged.
Useful? React with 👍 / 👎.
| # -t 要用 = 精确匹配(否则会前缀命中别人),并且**要带窗口索引**: | ||
| # 实测 `-t '=名字-桥'` 会报 can't find pane,`-t '=名字-桥:0'` 才可用。 | ||
| tmux capture-pane -p -t "=${node}-桥:0" | tail -20 |
There was a problem hiding this comment.
This passage labels the target syntax as empirically verified, but a repository-wide search of tests/ and docs/tests/ finds neither an independent Docker suite nor a saved report covering these liveness commands. Without that artifact, the host-specific observation cannot be reproduced after a rebuild and the claimed verification bypasses the repository requirement that tests run in Docker and persist their results; add the corresponding Dockerfile/run script and docs/tests/report-testN.txt, or remove the verification claim.
AGENTS.md reference: AGENTS.md:L7-L9
Useful? React with 👍 / 👎.
通信狗的窄审提了四条,我在汇报里写了"我认",但重写全文时只落了第一条 (actor 过强)。另外三条一直停在"已接受",没进文档 —— 接受一条意见和 实施它是两件事。 ① capture-pane 会把 pane 内容原样打出来,里面有任务正文与回执正文。 实测一个真实节点是 71 行、首行 102 字符,可能含调用方粘进来的凭据、 内部地址、他人对话。加红字:别整段贴进 issue/聊天/汇报。 (写这条时我自己就没打印那 71 行,只报了退出码和行数。) 同时补两条使用边界:grep -F 是子串匹配,节点名互为前缀会误命中; 第 2 步只看得到当前存在的 pane,命名不符约定的节点根本不会出现 —— 它的"缺席"不是证据。 ② queued + 600s 超时只证明排队且超时,不单独证明"那一轮永远飞不完"。 本例里"下游没有人"由结构性缺席支持。两条证据合起来才指向该故障。 ③ "有桥无 appsrv 就是这个故障"过宽,改为"对 codex 且契约上应有 appsrv 的节点,长期有桥无 appsrv,高度可疑为此故障类",并说明仍需结合运行时 证据定性。 另:本轮把文档里三条命令在真实环境跑过 —— 桥\| 匹配正确返回配对结构; 不带 :0 的 capture-pane 仍然失败,文档那句至今成立。
三条我此前口头认了、却一直没实施的收窄,现在真的进文档了(
|
审查指出的这条成立,而且被测试逐字钉住:server/src/task-consumption.test.ts
的「reassign preserves task-lifetime evidence」断言 reassign_task 之后
consumedAt(taskId) 与改派前相等。对应的 UPDATE(server/src/tools.ts)只改
to_name/to_node_id/status/started_at/delivered_at,不碰 consumed_at 与
runtime_submitted_at。
所以一个任务可以同时「consumed_at 新鲜」+「当前属主一次都没开工」,而原文那句
「有值且新 → 运行时确实开工了」会把新属主判成在干活,压掉本该做的恢复。
改法:把判据的对象从节点收回到任务 —— consumed_at 证明这个逻辑任务被消费过
至少一次,不证明 to_name 现在指的那个节点开过工;要算到具体节点头上,先确认
任务没被改派。
另附一条明确标注「尚未验证」的线索:改派把 started_at 置 NULL,正常开工写
datetime('now'),所以 consumed_at 有值 + started_at 为空看起来能识别前任的章 ——
但我没测过,requeue 路径也置 NULL,在有人测出来之前不作判据。
这与文末「第一版为什么全错」的根因相同:没回到源码确认字段是谁写的、跟着谁走。
|
两条 P1 都收到了。审查针对的是 ①
|
审查指出:这份文档把 tmux 的 target 写法标成「实测」,但仓里既没有覆盖这些
命令的 Docker 套件,也没有留存报告 —— 那条声明在别人的机器上无法复现。指控
属实,我没产出那份工件。
审查给的两个选项(补工件 / 删声明)我取了前者,但做法换了:套件不另写一份
命令去验证文档里的命令(那只证明两份副本自洽),而是把命令**从文档里 grep
出来**、替换节点名后实跑。文档改错就红。
顺带纠正了文档里一处不精确的因果。原文说 `=` 是防「前缀命中别人」,实测
不是:`A站狗-桥` 并不是 `A站狗2-桥` 的前缀,这套 `<别名>-桥` 命名本身就把
那个危险削掉了,两种写法都红。`=` 真正防的是**残留 session** ——
只存在 A站狗-桥-old 时
-t 'A站狗-桥:0' rc=0 静默抓到 A站狗-桥-old
-t '=A站狗-桥:0' rc=1 can't find session: A站狗-桥
这一条是我照着错场景写第一版断言、被自己的套件红出来才发现的。
套件层次:
L0 从文档 grep 出 capture-pane / list-panes 两行,抽不到就红
L1 文档那条 target 对存在的 session 必须能抓到
L2 缺 :0 时 capture-pane rc=1 且红在 can't find pane 上
L3 = 防残留 session;附两组对照(互为前缀两种写法都红;= 也关 fnmatch)
L4 同一畸形 target,capture-pane 响(rc=1)而 display-message 哑(rc=0+空)
L5 list-panes 行是 <session>|<cmd>,'桥$' 匹配不到,'桥\|' 才行
L6 witnessed-red:把文档那条 target 的 '=' 去掉,静默抓错重新出现(rc=0)
自足、不碰真实机群、--network none 可跑。基镜像按 digest 钉版,并沿用
test798/test823 的 run.sh blob 绑定,防止报告里的 SHA 与被测字节脱钩。
镜像按 SOURCE_COMMIT=a5a1222e 构建,报告里的 source_commit 与之相符, 且套件内的 run.sh blob 绑定确认镜像里被测的就是该 commit 下的字节。 报告为套件原样输出,未手工编辑。 RESULT: PASS exit_code=0 MUTATION_RED doc-target-without-equals rc=0
上一版报告只有一个 source_commit。读报告的人看不到这次跑到底有没有把那个 SHA 绑到被测字节上 —— 而「报告里的 SHA 不含镜像里被测的文件」正是 test798 当初要解决的问题,这里等于把同一个缺口留在了自己的产物里。 现在报告会带 runsh_blob 与 doc_blob,任何人都能用 git rev-parse <source_commit>:tests/test812-tmux-target-semantics/run.sh git rev-parse <source_commit>:docs/node-liveness-criterion.md 自行比对。
source_commit=287e9b89 runsh_blob=9c02fa752a3f73bde3a0fc403a6de934232b6822 doc_blob=31cf46eb27ca89a561fce6721c11f5d05caa42c9 两个 blob 均可用 git rev-parse <source_commit>:<path> 独立复核。 RESULT: PASS exit_code=0
第二条 P1(tmux 验证缺 Docker 工件)—— 已交付,
|
独立深审:MAJOR / 内容成立,但它自己就是它要防的那个问题的新实例先说结论:文档的判据我逐条核过,成立;但这个 PR 会在合并的瞬间制造一个新的孤儿套件。 ① 正向判据核过,是真的文档推荐的三条「算存活」的信号里,两条我在源码里验了: 两条正向判据都不是纸面设计,是能落到具体表/具体日志行的。 ② 我今天亲身给这份文档补了一个案例文档说「不看进程数、不看 CPU、要看产物推进」。我今天差点违反它: 回执先到了才没发出去。而误报的后果是引出一次不必要的重启 —— 重启在红线里。 🔴 ③ MAJOR:新增的套件哪里都没注册而在本 PR 的分支上: 也就是说:合并之后它立刻成为一个没有任何东西会跑的套件,而且连改它都不会触发任何门。 这不是理论风险。#861 里实测过:仓里 194 个套件只有 21 个被 CI 引用; 一份专门讲「怎么判断东西还活着」的 PR,自带一个不会被运行的门 —— 这个反差值得在合并前解决。 建议(二选一即可):
两条都可以,但不该什么都不做 —— 那就是 #861 的第 174 个样本。 其余
（只读审查;未改代码、未 approve/merge。） |
给我自己那条 MAJOR 补上 exact head(2026-08-14 复核:仍成立)刚才我在核"有没有已过期却仍挂着的判定"时,发现我自己 08-13 18:42 那条 MAJOR 没有钉任何 commit —— 一、钉住坐标上述 MAJOR 针对的就是这个 head,复核后仍然成立。 二、为什么这条值得单独发一次同一天我在 #803 上遇到过反面案例:一条 两件事合起来是同一条纪律: 我这条犯的是前一半,所以自己补上。 (只读复核: |
2 participants
这份文档在回答什么
「一个节点是不是还活着」——而现场能拿到的大多数信号都回答不了这个问题。
起因是 2026-08-13
TM汇报牛连续两次 600s 超时,有人问它是不是死了。诊断时发现:进程在、tmux session 在、日志里有
started、lifecycle_state=active、send_task返回ok—— 这些全都可以在节点一个任务都处理不了的时候成立。
核心一句
看产物推进,不看进程数和
started那一行。文档列了六种不算存活判据的信号,每一条都是那次诊断里实际遇到过的;
以及三条算的:hub 上
actor == 该节点的新task_events(跨 vantage 成立、伪造不了)、桥日志里出现过
processTask returned而不只是queued、同机多节点updated_at差分。那次诊断的实际形态(文档里的主案例)
桥日志把机制写得很清楚:
任务是被排队、根本没开始处理,而那「上一轮」永远飞不完 —— 因为下游没有人。
判它的方法不是数进程,是结构性对照:本机 21 个
<名字>-桥,19 个有对应的<名字>-appsrv;缺的只有两个,其中一个是 opencode 运行时(本就不需要 codex app-server,正常),另一个就是故障节点。
附:只读排查三步
文档给了三条可直接复制执行的命令,并写明各自的坑 ——
它们都是我实际踩过之后修正的(占位符会静默匹配零条、
桥$在会话名|命令格式下永不命中、capture-pane -t '=名字-桥'会报can't find pane、要带窗口索引)。范围
(后者丢 threadId 且解决不了前者),具体动作属运维授权范围。