「unknown」不是答案:执行端重启后,后台 shell 该由谁来对账

一次执行端修正:重启后的 Host 不再把「我不知道」原样交给 agent,而是查一遍进程表,再给出一个能拿来做下一步的结论。
1. 一个谁都答不了的问题⌗
MaxClaw 里,agent 的循环跑在主进程,shell 这类机器工具跑在单独的 Tool Host 进程里。长命令会转成后台会话:shell 先采样几秒,然后返回一个 session_id,命令在后台继续跑,agent 之后用 shell_session 的 list / poll / wait / kill 去管它。
Host 有一份会话日志(journal):命令、启动时间、已经保存下来的输出、退出码。Host 正常退出时,所有会话都会被收尾。麻烦出在非正常重启(崩溃、被 SIGKILL、热更新时被替换):日志里有一批会话「开始了,但没有结束记录」。
改动之前,重启后的 Host 对这些会话的回答是这样的:
status: exited ? 'exited' : 'unknown',
note: 'The Tool Host restarted before recording an exit. This is the last saved output,
not proof of termination. The original process may still exist; it has not been
restarted or killed by recovery.',
每一句都对,可没有一句能用来做决定。后果是连锁的:
| 动作 | 改动前的结果 |
|---|---|
shell_session list | 列出一个 status: unknown 的会话 |
shell_session kill | 失败:Host 手里没有这个子进程的句柄 |
| 回合结束的自动收尾 | 报「未能终止,可能仍在运行」 |
| agent 能做什么 | 自己去 ps 里按命令行猜,或者带着不确定收工 |
最后一行是关键。agent 知道的不比 Host 多,它也只能 ps aux | grep。按命令行文本去认进程,碰到同一条命令跑了两份、或者 PID 被别的进程复用,就会认错。这个判断本该由手里有更多信息的一方来做,而那一方就是 Host。
2. 证据早就在磁盘上,只是没连起来⌗
有意思的是,回答这个问题需要的东西,系统里本来就有一半。
Host 早就有一个 PID 账本(shell-pid-ledger.ts),用来处理 Host 崩溃后留下的孤儿进程组:每启动一个会话,就记下领头进程的 PID 和启动时间;下次启动时扫一遍上一个实例的账本,比对进程表,只报告,不杀——「由运维决定」。
但账本和会话日志是两本账。日志知道「会话 X 没有退出记录」,账本知道「PID P 的进程组还在」,没有任何代码把 X 和 P 对上。所以这次改动做的第一件事很朴素:日志的每条记录也存下领头 PID。
// shell-session-store.ts:记录 schema 新增两个字段
pid: z.number().int().optional(),
/** Set when a restarted host settled an exit the previous host never recorded. */
ended_by: z.enum(['host-restart', 'killed']).optional(),
改动前写下的旧记录没有 pid,就退回账本去查(ledger.recordOf(sessionId, ownerId))。两边都查不到,才算真的没有证据。
3. 怎么认出「还是那个进程」⌗
有了 PID 还不够,PID 会被复用。Host 重启可能隔了几分钟,原来的 PID 可能早就分给了一个毫不相干的进程。认错了的后果很严重:你会把 kill 发给别人的进程组。
判定复用了孤儿扫描用的同一个匹配器 matchOrphanedGroups,规则是:
读一次进程表:ps -A -o pid=,pgid=,etime=,command=
对记录的 (pid, started_at):
有进程 PID == pid
且启动时间与记录相差 > 3s → PID 已被复用,不是我们的:判「已结束」
进程组 == pid 且启动不早于记录的成员:
领头在 或 至少有一个成员在 → 「仍在跑」,报告整个组
都不在 → 「已结束」
几个细节:
- 用
etime而不是lstart。 已运行时长和时区无关,现在 − etime就是启动时刻。ps的 etime 精度是 1 秒,加上进程从 spawn 到 exec 在负载高时有一点延迟,所以容差是START_TOLERANCE_MS = 3_000。 - 领头死了、组还在,算在跑。 后台会话是
setsid出来的独立进程组,常见情形是领头的 shell 已经退出,真正干活的子进程还挂在同一个组下。只看领头 PID 就会误判成结束。 - 成员也要过时间这一关。 只算启动时间不早于会话的成员,防止一个碰巧复用了这个组号的新组被认成旧会话。
测试把复用的情况单独钉了下来:
expect(judgeRecoveredShell(r, { ...probe, processes: () =>
[{ pid: 424242, pgid: 424242, startedAt: r.started_at + 60_000, command: 'reused' }] }))
.toMatchObject({ verdict: 'ended' })
同一个 PID,启动时间晚了 60 秒,就不是那个会话。
4. 三种结论,各自带着能用的东西⌗
shell-recovery.ts(60 行)只做一件事:给一条没有退出记录的会话下结论。
export type RecoveredShellVerdict =
| { verdict: 'ended'; checked_at: number }
| { verdict: 'running'; checked_at: number; pgid: number; group: OrphanedShellGroup }
| { verdict: 'unconfirmed'; checked_at: number; reason: string; next_step: string }
| 结论 | 什么时候 | agent 拿到什么 |
|---|---|---|
| 已结束 | 进程组不在了,或 PID 被复用 | status: exited、ended_by: host-restart、ended_at,明说退出码没记录 |
| 仍在跑 | PID + 启动时间对上了 | status: running、pgid、组内进程列表;shell_session kill 可以直接停 |
| 无法确认 | 检查本身做不了 | status: unknown,外加 reason 和一条具体的 next_step |
第三种不是把「unknown」换个名字。它只在检查本身做不成时出现,而且每种情况都说清楚为什么、下一步做什么:
| 原因 | next_step 给的是 |
|---|---|
| 日志和账本都没有 PID(Host 在启动会话和记下 PID 之间就死了,或记录太旧) | 用 ps -eo pid,pgid,etime,command 找这条命令,kill -TERM -<pgid> 停整个组 |
| Windows Host(没法按启动时间把进程对上会话) | Get-Process -Id <pid> | Format-List Id,StartTime,Path,确认是这条命令再 Stop-Process |
读不了进程表(ps 失败) | 稍后重试 list / kill,或 ps -o pid,etime,command -g <pgid> 手查 |
拿不准的时候,系统选的是「说明白为什么拿不准」,而不是猜一个看起来更干净的答案。这和孤儿扫描「只报告不杀」是同一个立场:认不准身份,就不替任何人动手。
5. 写下来的和每次重算的⌗
这里有一个不对称,是整个设计里我觉得最对的地方:
已结束 → 写回日志(ended_at = 检查时刻,ended_by = host-restart)
仍在跑 → 不写,每次访问重新判
无法确认 → 不写,每次访问重新判
理由写在注释里:「消失」是单向的,一个进程组没了就不会回来,可以落盘成事实;「还在跑」和「判不了」都会变——进程下一秒可能就退出,ps 下一次可能就成功。如果把「running」写死,下一次 list 就会报一个其实早就结束了的会话。
所以对账发生在两个地方:
- Host 启动时,
run-tool-host.ts里调一次reconcileRecoveredShellSessions(),把三类结果打到日志里(失败只告警,不阻止启动); - 每次
list / poll / wait / kill碰到一条未结算的恢复会话时,再判一次。
为了不让一次 list 对 N 个会话跑 N 次 ps,探针包了一层缓存:
/** One process-table read per probe, however many sessions it judges. */
export function cachedProcesses(read: () => readonly PsProcess[]) {
let rows: readonly PsProcess[] | undefined
return () => (rows ??= read())
}
还有一个措辞上的诚实:ended_at 是发现它不在了的时刻,不是它真正结束的时刻。返回给 agent 的说明是「ended no later than that」,收尾报告里写的是「最迟 … 已结束」。退出码填 null,并说明没记录——不编一个 0 出来让结果看起来更好。
6. kill:只动验证过的组,动完再验一次⌗
能确认在跑,才能杀;杀了还要确认真的没了。
shell_session kill <id>
│
├─ 判定 = 仍在跑 → terminateProcessTree(pgid) # SIGTERM,宽限后 SIGKILL
│ │
│ └─ 再判一次
│ ├─ 已结束 → 写 ended_by: killed、consumed,删账本条目
│ │ 返回 terminated: true
│ └─ 还在 → 失败,列出残留 PID 和一条 ps 手查命令
│
├─ 判定 = 无法确认 → 失败,error 里带 reason 和 next step
│
└─ 判定 = 已结束 → 幂等成功:already_finished,terminated: false
kill 本来就是幂等的(目标状态是「不在运行」,已经结束也算达成),恢复会话沿用了这一点:第二次 kill 返回 already_finished: true。
回合结束的自动收尾也跟着改了。以前一个随 Host 重启而结束的会话,在收尾时会出现在「未能终止,可能仍在运行」那一栏;现在它有自己的一栏:
[后台 shell 收尾] 已随 Tool Host 重启结束(重启后的 Host 核对进程组已不在,退出码未记录):
<会话>:最迟 <时刻> 已结束
同一件事从「失败,可能还在」变成了「结束了,最迟在什么时候」。agent 读到前者会去补救,读到后者可以直接收工。
7. 测试怎么证明这件事⌗
新增的 shell-recovery.test.ts(116 行,4 个用例)里,最有分量的是第一个:它不是在内存里伪造一条记录,而是真的起一个 Host 实例(shell-recovery.fixture.ts),让它启动 echo before-restart; sleep 30 这样的长命令,然后在没写退出记录的情况下直接 process.exit(0)。之后在测试进程里用同一个日志目录当「重启后的 Host」:
| 用例 | 验证的是 |
|---|---|
| 仍在跑 | 日志里有 pid 且没有 ended_at;对账报 running 并带组号;list 显示 recovered: true;kill 后组确实没了(process.kill(-pid, 0) 抛错),日志记 ended_by: killed;第二次 kill 幂等 |
| 已结束 | 用一个已退出进程的 PID 写记录;对账写回 ended_by: host-restart,ended_at 不早于检查开始;list 的运行中列表为空、出现在已结束列表;收尾报告含「已随 Tool Host 重启结束」 |
| 无法确认 | 没有 PID 的记录保持未结算;kill 失败,reason 提到 process id,next_step 含 kill -TERM -<pgid> |
| 纯判定 | 旧记录从账本取 PID;进程表为空 → 结束;PID 复用 → 结束;ps 失败 → 无法确认且带错误;Windows → 无法确认且给 Get-Process 命令 |
第一个用例覆盖的路径,恰好就是这次要修的那条:一个真实的进程,比生下它的 Host 活得更久。
8. 没解决的,和为什么这样已经够了⌗
这次改动没有假装把一切都恢复了:
- 重启后的输出接不上。 新 Host 不是那个进程组的父进程,拿不到它的 stdout。返回结果里明写:「这是最后保存的输出,
shell_session wait跟不了它」。能做的只有看着它(list)或者停掉它(kill)。 - Windows 一律无法确认。 没有可靠的启动时间匹配,就不冒险认身份;退而给一条能手查的 PowerShell 命令。
- 退出码永远是 null。 不知道就是不知道。
常见的做法大概有三种:重启时把记录里的 PID 一律杀掉(PID 复用时会误杀);把这些会话统统标成丢失(真正还在跑的进程就没人管了);或者像改动前那样,把 unknown 原样交出去。这次的做法是第四种:用身份证据(PID + 启动时间)把能确定的都确定下来,把能落盘的事实落盘,把会变的状态留着每次重算,剩下真判不了的,连原因和下一步一起交出去。
agent 面对一个后台任务,需要的不是一份关于不确定性的免责声明,而是一个能直接行动的状态。手里有进程表的是 Host,这一步就该它来做。