一次执行端修正:重启后的 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 就会报一个其实早就结束了的会话。

所以对账发生在两个地方:

  1. Host 启动时,run-tool-host.ts 里调一次 reconcileRecoveredShellSessions(),把三类结果打到日志里(失败只告警,不阻止启动);
  2. 每次 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,这一步就该它来做。