Kun Runtime 自重启租约恢复修复:同实例控制防护、优雅租约交接与恰好一次续跑
Kun Runtime 自重启租约恢复修复:同实例控制防护、优雅租约交接与恰好一次续跑
导读
Kun 是一个 Local-first 的 AI Agent 工作台,用同一个 Runtime 同时支撑桌面 GUI 与 TUI,并由 Service Manager 统一监督线程状态与执行租约。本篇文章围绕 fix-runtime-self-restart-lease-recovery 变更提案 展开,讲解一个此前真实存在的稳定性缺陷:Runtime 可以对自己执行 kun runtime restart,在活动回合尚未完成挂起(suspend)时提前清空本地执行租约,导致 Manager 以 owner_lease_expired 终结仍在运行的回合,把本可恢复的对话留在失败状态,而 goal 与 todos 仍处于活动状态。读完本文,你将掌握该修复的三个核心能力——同实例控制安全(same-runtime-control-safety)、优雅回合租约交接(graceful-turn-lease-handoff)、Manager 结算式中断恢复(manager-settled-interruption-recovery),以及它们在 CLI、租约客户端、Runtime 关停编排、回合持久化与启动对账、渲染器语义中的完整实现细节。
问题背景:Runtime 为何会"自杀式"重启
Kun 的架构中,一个共享的 Runtime 由 Service Manager 监督,二者职责边界清晰:
- Manager 是线程状态的唯一写入者,并持有带 fencing(围栏令牌)的执行租约;
- Runtime 负责执行回合(turn),并周期性续租这些执行租约。
缺陷的触发路径如下(见 design.md 的 Context 章节):
- 由 Runtime 承载的 agent shell 可以对该实例自身执行
kun runtime restart; - 关停期间,租约客户端在活动回合完成挂起之前就丢弃了本地租约映射,导致随后的 release 变成空操作(no-op);
- 替代 Runtime 启动时观察到旧的 Manager 租约仍然存在,从而跳过孤儿恢复;
- 租约到期后 Manager 写入
owner_lease_expired,活动 goal 因此被遗留为"悬空"状态。
修复范围横跨 CLI 身份识别、shell 环境过滤、租约客户端生命周期、Runtime 关停顺序、回合/goal 持久化、启动对账与渲染器 canonical 状态处理,而 Manager 的 fencing 与既有重启授权依然是安全边界。
该变更的目标与非目标(Goals / Non-Goals)可以概括为:
- 目标:仅拒绝来自 agent 控制执行的同实例 stop/restart;在 Runtime 注销前释放全部 Manager 执行租约并在释放确认前保持 fencing;在优雅挂起释放所有权前持久化精确测得的 goal 已用时间;对
owner_lease_expired中断做分类与恰好一次续跑(包括没有持久化终态码的旧记录);保持 goal/todos 投影 canonical 并提供安全的 Manual 恢复兜底。 - 非目标:不提高租约 TTL、不接收无有效 mutation fence 的写入;不引入通用的活动回合重启禁令、不新增 force 标志、不改变受信外部/GUI 重启授权;不重建第二 Runtime 或旧式 provider/process-manager 界面;不把重启进程清理扩散到普通启动、watchdog、更新器或 GUI 退出路径;不新增或版本化 HTTP 路由、SSE 事件或 Manager 租约协议 DTO;不为硬崩溃或 Runtime 停机估算已用时间。
能力一:同实例控制安全(same-runtime-control-safety)
设计决策:以精确 Runtime 身份作为自我控制边界
Runtime 本身已拥有 KUN_RUNTIME_INSTANCE_ID(在 runtime-server-start.ts 中通过 randomUUID() 生成并写入 process.env)。修复方案将该非机密标记加入 agent shell 的安全环境白名单,而不是采用"活动回合门禁"或 PID 匹配:
- 活动回合门禁的缺陷:受信的外部重启本就应该允许打断并恢复工作,因此不应被通用门禁拦下;
- PID 匹配的缺陷:discovery 中的实例身份本来就是权威的生命周期身份,比 PID 更可靠。
双次身份检查
在 CLI 发送 stop/restart 关停请求之前,会做两次实例身份比对:
- 初始检查:将环境中的实例标记与目标 discovery 记录的
instanceId比对——即使目标健康端点不可用也要比对; - 最终检查:在发送关停请求前,立即对最终检视到的记录再次比对。
身份相等时,CLI 返回 exit code 70 与稳定错误码 runtime_self_control_forbidden,并且不发送任何关停请求;标记缺失或不等时,保持外部控制行为不变。
对应源码位于 shared-runtime-command-guard.ts:
export function assertRuntimeSelfControlAllowed(
inspected: SharedRuntimeInspection | null,
callerRuntimeInstanceId: string | undefined
): void {
if (!callerRuntimeInstanceId || inspected?.discovery.instanceId !== callerRuntimeInstanceId) return
throw new Error(
'runtime_self_control_forbidden: cannot stop or restart the Runtime that is executing ' +
'this command; use the GUI or an external terminal'
)
}
同一文件中的 assertOneShotRuntimeControlAllowed 在自我控制检查之外,还会拒绝针对 clientOwnerKind(如 GUI/TUI)持有的 Runtime 执行一次性 stop/restart,提示应先关闭或重启对应客户端。
安全环境传播:只放行身份,不放行密钥
agent shell 的 spawn 环境采用小型执行白名单而非继承 Runtime 全部环境(见 builtin-shell-utils.ts 的 SAFE_SHELL_ENV_KEYS):包含 PATH、HOME、USER、SHELL、TMPDIR、LANG 以及 KUN_RUNTIME_INSTANCE_ID 等基础变量,并额外放行 LC_*;Windows 侧另有 SAFE_WINDOWS_SHELL_ENV_KEYS 且会把 System32 等核心目录追加到 PATH(绝不前置)。关键约束是:Manager token、Runtime token、API Key、模型凭据等一律过滤,shell、verifier、operation、hook 或 SDK 子进程永远无法把它们打印进工具结果。该标记只是"意外的自我控制守卫",不是授权密钥,既有的认证生命周期控制仍是安全边界。
测试验证
shared-runtime-command.test.ts 覆盖了核心场景:
- 对
stop/restart均断言:健康探测不可用时(fetch 返回 503),同实例命令仍返回 exit code 70、stderr 含runtime_self_control_forbidden,且没有任何 POST 关停请求发出; - 无标记或标记为其他实例时,保持外部生命周期控制行为(POST 请求正常发出);
- 一次性命令针对 GUI/TUI 持有的 Runtime 时也返回 exit code 70 与"runtime is owned by ..."提示;
- 不会停止无 owner 的 Runtime,也不会从一次性 restart 启动 replacement。
能力二:优雅回合租约交接(graceful-turn-lease-handoff)
租约关停成为异步释放屏障
ThreadExecutionLeasePort.shutdown 的契约从同步变为 Promise<void>(见 thread-execution-lease.ts 的 shutdown?(): Promise<void>)。Manager 侧租约客户端 manager-thread-execution-lease-client.ts 引入 open / closing / closed 三态与一个缓存的 shutdown promise,closing 状态下:
- 阻断新的租约获取(
acquire在state !== 'open'时直接抛错); - 停止续租调度(
stopAllRenewals清理 interval、retry 与 deadline 定时器); - 等待所有 in-flight 获取完成(
finishShutdown先Promise.allSettled(pendingAcquires)); - 对成功但迟到的获取立即释放,绝不把它当作可运行所有权返回;
- 按"完整租约代数(lease generation)"去重普通释放与关停释放;
- 并行排空剩余全部租约。
租约映射与 mutation fence 会一直保留,直到 Manager 确认该代数已释放或已不存在;{released:false} 是幂等成功。若在有界的重试(LEASE_RELEASE_ATTEMPTS = 3)之后仍以传输失败告终,则该代数的 fail-closed fence 继续保留、不阻塞其他释放、并汇入一个聚合关停错误。同线程/同回合在释放 pending 期间的再获取会等待该释放确认,因为 Manager 可能仍返回当前的 fencing token;随后按代数比较防止不同代数的迟到响应清掉更新的所有权。该设计不需要单独的公开 drain 方法,也不需要改动 Manager 协议。
Runtime 关停顺序:所有权保持到挂起状态持久化
关键顺序是(详见 design.md 的 Decisions 章节):
- 关闭 TurnService admission 门并等待已进入的 start / steer / Graph-resume mutation 离开 admission 临界区(测试见 turn-service-shutdown-admission.test.ts:
closeAdmissionForShutdown期间新 start 与新 Graph resume 均抛 "runtime is shutting down",而已进入的 start 会等它 settle 完); - 停止 resume 调度器、quiesce Graph workers;
- 以
releaseLease: false挂起 Direct 与 Graph 回合; - 停止 Graph,并在既有 active-run 边界内等待;
- 等待租约客户端释放屏障完成;
- 最后才关闭持久化 store 并注销 Runtime。
goal 与普通自动续跑与 HTTP、Graph、review、extension 回合一样,都通过 host 持有的 active-run 追踪器启动,因此它们的挂起清理也在这个边界内。挂起的 AgentLoop 清理会调用 goalTurns.afterSuspended——它在 goal-turn-coordinator.ts 中只做一件事:对同一 goal 代数精确结算一次可靠的已用计时器(finishElapsedTimer),不触发任何终态续跑策略,也不估算停机时间。
各关停阶段独立收集失败:挂起、Graph stop 或 active-run 拒绝不能跳过后续的租约排空;若某个 run 在既有边界内未能 unwind,关停继续推进且不估算已用时间。释放失败会报告,同时剩余清理照常执行——Manager 的租约到期依然是 fail-closed 兜底。
只结算可靠测得的 goal 时间
afterSuspended 与普通终态路径(afterTerminal)的差异在于:挂起路径只结算计时、不评估续跑。这保证了:
- 活动 goal 因计划内 Runtime 替换而挂起时,在释放租约前精确结算一次该 run 的已用时间;
- replacement 续跑时创建新的计时器,关闭到恢复之间的间隔不计入;
- 硬崩溃导致无法可靠测量挂起时间时,保留最后一次持久化的已用值,绝不估算额外时间(这正是非目标中"不为硬崩溃或 Runtime 停机估算已用时间"的落地)。
能力三:Manager 结算式中断恢复(manager-settled-interruption-recovery)
Turn 契约新增可选字段
TurnSchema(turns.ts)新增两个可选字段:
terminalCode:有界(1~128 字符)的机器可读终态原因;managerLeaseSettlement:Manager 直接终结回合时写入的内部结算来源,其 schema(turns.ts)固定为code: 'owner_lease_expired',并携带ownerFlavor、ownerInstanceId、fencingToken与settledAt时间戳。
两个字段都是 optional,因此旧数据无需迁移仍可读。公共 thread/turn 投影会在 thread-projection.ts 的 projectPublicTurn 中把这两个恢复专用字段剥离(连同 steeringDeliveries),渲染器面对的仍是既有的 canonical error item。无需改动任何 HTTP 路由、SSE 事件、租约 TTL 或 Manager 协议版本。
Manager 侧:注册前先结算前任租约
Manager 的注册流程增加了一道过期租约屏障:注册替代 Runtime 之前,先让前任 Runtime 的过期租约全部过期并持久化结算每一个。实现位于 shared-data-store-core.ts 的 reconcileExpiredLease:
- 只允许 Manager 结算孤儿回合——Runtime 永远不能清扫另一个 Runtime 的存活回合;
- 把活动回合终结为
failed,写入terminalCode: 'owner_lease_expired'、完整managerLeaseSettlement(含 owner 实例与 fencing token)与error; - 写入确定性 error item(id 形如
item_<turnId>_owner_lease_expired,message 为 "Turn owner stopped heartbeating.",code 为owner_lease_expired,severitywarning),并追加turn_failedSSE 事件; - 已健康完成的租约不会凭空制造新失败。
对应测试 service-manager-registration-reconciliation.test.ts 验证:dead owner 的回合被结算为 failed + terminalCode: 'owner_lease_expired' + settlement 指向旧实例后,replacement 才注册成功,且线程不再要求 mutation fence;而 reconcileExpiredLease 失败时(第 87-124 行)replacement 不被接纳(fail closed)。
Runtime 侧:启动对账与恰好一次续跑
每一种 Runtime 启动模式都会在一个有界的启动恢复窗口内扫描 Manager 结算过的中断(见 turn-service-runtime-state-operations.ts 的 reconcileManagerSettledInterruptions):
- 候选线程必须是
idle且为primary或fork,无 queued/running 回合,最新回合为failed; - 新记录:要求
managerLeaseSettlement.code === 'owner_lease_expired'且settledAt落在窗口内; - 旧记录(无新字段):要求最新失败回合的 canonical error item 精确匹配确定性 id(
item_<turnId>_owner_lease_expired)、kind 为error、code 为owner_lease_expired,且finishedAt在窗口内——绝不模糊匹配消息文本; - 只有确定性中断检查点被持久化成功后,该线程/turn 源才进入 goal 或普通续跑调度(checkpoint 冲突或存储拒绝则本轮跳过,fail closed);
- 调度严格绑定"最新失败回合"这一精确来源,并复用既有 cooldown/capacity 门;若扫描后又出现更新的回合,续跑 admission 会原子拒绝该来源回合;goal 路径中途不切换路径。
此外还有两条防御规则:
- 子代理恢复证据:可续跑 child 记录若指向的父回合不是该精确恢复来源,则被丢弃,不得用于改道或充实续跑;
- 非活动 goal 的普通续跑:线程保留 completed/paused/blocked/usage-limited 的旧 goal 记录时,走既有普通续跑路径,而不是丢弃或重启非活动 goal。
线程可续跑与否还有两个细节值得注意:
- 活动 goal 走 goal continuation;无活动 goal 的线程即使保留旧 goal 记录也走普通 continuation;
- 前台或非托管启动(不注册 Manager)打开含 Manager 结算中断的数据目录时,同样应用该有界窗口,不恢复任意久远的工作。
渲染器语义:显式 null 是权威清除
Runtime 快照字段采用两种语义(见 design.md):
undefined:provider 省略 goal/todos 时的兼容语义,保留既有投影/摘要值;null:权威清除,投影与 prefetch 缓存必须清掉旧值。
因此投影与 prefetch 回退判断一律使用 === undefined 而非 nullish 合并。迟到的 detail 响应会按 sequence、tagged turn、detail latest turn 与投影 latest turn 独立 fencing,防止它覆盖更新的 goal/todo/sidebar/live-turn 状态;身份过期的 tagged 响应也不会推进 SSE cursor(因为它没有导入高水位所代表的新事件)。
对 owner_lease_expired 的呈现,渲染器组件(测试见 MessageTimeline.runtime-error.test.ts):
- 本地化展示恢复引导(文案含 "ownership" 语义),保留原始 code/message 细节(
<pre>中仍显示owner_lease_expired); - 仅在整条线程 idle、最新已结算主线程回合、且父层提供 Continue 动作时暴露 Continue 控件;
- 线程 processing、存在更新回合或无 Continue 动作时,不展示重复 Continue 控件、也不自行启动恢复——自动恢复始终是后端所有(backend-owned)。
关停失败的风险与兜底
设计文档列出了四类主要风险及对策(design.md 的 Risks / Trade-offs):
| 风险 | 对策 |
|---|---|
| Manager 传输失败导致无法干净释放 | 排空每个租约、保留 fail-closed fencing、上报聚合关停错误、由既有到期对账安全兜底 |
| 迟到的 acquire/renew 响应与关停竞态 | 追踪 in-flight 获取、成功的迟到获取立即释放、closing 态响应禁止重装定时器/fence |
| 启动对账可能重复续跑 | 要求已提交的确定性 checkpoint、调度绑定精确最新失败回合、复用 cooldown/capacity 门 |
| Provider 数据伪造恢复码 | 新记录必须带 Manager 结算来源;旧数据仅接受精确 canonical item 与有界窗口,绝不模糊匹配 |
| 内部 Turn schema 新增字段 | 保持可选且有界,既有持久化回合与客户端不受影响 |
迁移方案上不需要一次性数据迁移:新失败会持久化 terminalCode;启动对账同时识别新记录与精确 canonical 旧错误项;回滚只需还原代码与可选字段读取器,已持久化的可选字段对旧 schema 无害。
变更影响面与验证
影响模块
该修复触及(见 proposal.md 的 Impact):Runtime CLI、安全 shell 环境、Manager 执行租约客户端、Runtime 关停组合、goal 生命周期、回合持久化与启动对账、渲染器快照对账与运行时错误呈现,以及 Kun/TUI 文档(kun-tui.md 已记载:kun runtime stop/restart 不停止 GUI/TUI 持有的 Runtime;Agent 工具针对承载自身的 Runtime 执行生命周期命令以 runtime_self_control_forbidden 拒绝)。
测试与验证状态
任务清单 tasks.md 显示全部 5 组任务已完成,验证覆盖:
- CLI 与 shell 环境测试:同实例、外部、unhealthy-discovery、secret-filtering 场景(shared-runtime-command.test.ts);
- 租约客户端、Runtime 顺序、Graph/Direct 挂起与 goal 已用时间回归测试(agent-loop-host-shutdown.test.ts、turn-service-shutdown-admission.test.ts、goal-turn-coordinator.test.ts);
- 持久化、legacy 兼容、跳过条件与去重恢复测试(turn-service-manager-reconciliation.test.ts、service-manager-registration-reconciliation.test.ts);
- 渲染器 reducer、缓存、终态与运行时错误组件回归(MessageTimeline.runtime-error.test.ts)。
验证说明中如实记载:聚焦恢复测试与变更文件 ESLint 通过;完整 typecheck/build 受共享 checkout 的 Zod 4.5.4/4.4.3 分裂(默认堆 Kun build 亦耗尽内存)阻塞,完整测试保留无关的原生模块 ABI 与 catalog 基线失败,仓库级行数门保留既有 758 行的 kun/src/manager/service-manager.test.ts 失败;变更的每个 authored 文件均未超过 700 行门限。
小结
这次修复把"Runtime 自我重启"从一个会导致对话永久失败的稳定性缺陷,转变为一条完整的安全与恢复链路:同实例拒绝(身份标记 + 双次检查)→ 优雅挂起(admission 门 + active-run 屏障 + 精确计时)→ 租约异步释放屏障 → Manager 持久化结算 → 启动对账恰好一次续跑 → 渲染器 canonical 呈现与手动 Continue 兜底。对于正在排查 Kun 中"回合因 owner_lease_expired 失败却无法恢复"问题的开发者,可以从三个层面验证修复是否生效:在 agent shell 里尝试对自己执行 kun runtime restart 应得到 exit code 70;重启后目标线程应带着同一 goal/todos 恰好续跑一次而不是重复续跑;GUI 中该错误应展示本地化恢复文案与 Continue 控件(仅在线程空闲且为主线程最新回合时)。若你想深入源码,建议从 shared-runtime-command-guard.ts、manager-thread-execution-lease-client.ts 与 turn-service-runtime-state-operations.ts 三处入手。