Kun Runtime 自重启租约恢复修复:同实例控制防护、优雅租约交接与恰好一次续跑

原创2026-10-11 09:14:061,604 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

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 章节):

  1. 由 Runtime 承载的 agent shell 可以对该实例自身执行 kun runtime restart;
  2. 关停期间,租约客户端在活动回合完成挂起之前就丢弃了本地租约映射,导致随后的 release 变成空操作(no-op);
  3. 替代 Runtime 启动时观察到旧的 Manager 租约仍然存在,从而跳过孤儿恢复;
  4. 租约到期后 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 关停请求之前,会做两次实例身份比对:

  1. 初始检查:将环境中的实例标记与目标 discovery 记录的 instanceId 比对——即使目标健康端点不可用也要比对;
  2. 最终检查:在发送关停请求前,立即对最终检视到的记录再次比对。

身份相等时,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 章节):

  1. 关闭 TurnService admission 门并等待已进入的 start / steer / Graph-resume mutation 离开 admission 临界区(测试见 turn-service-shutdown-admission.test.ts:closeAdmissionForShutdown 期间新 start 与新 Graph resume 均抛 "runtime is shutting down",而已进入的 start 会等它 settle 完);
  2. 停止 resume 调度器、quiesce Graph workers;
  3. 以 releaseLease: false 挂起 Direct 与 Graph 回合;
  4. 停止 Graph,并在既有 active-run 边界内等待;
  5. 等待租约客户端释放屏障完成;
  6. 最后才关闭持久化 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,severity warning),并追加 turn_failed SSE 事件;
  • 已健康完成的租约不会凭空制造新失败。

对应测试 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 组任务已完成,验证覆盖:

验证说明中如实记载:聚焦恢复测试与变更文件 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 三处入手。

登录后查看全文
Kun