qinglong/docs/adr/ADR-0118-remote-worker-lease-control-and-durable-timeout.md

ADR-0118：Remote Worker Lease Control 与耐久 Timeout

• 状态：Accepted（生产 route composition 已由 ADR-0119 接入、共享 Artifact adapter 已由 ADR-0120 实现、Worker execution composition 已由 ADR-0121 实现；完整 Worker 产品生命周期仍默认关闭）
• 日期：2026-07-23
• 关联 RFC：QL-RFC-0001 D-25、D-71、D-85、D-108、D-111、D-115、D-116、D-117
• 关联 ADR：ADR-0012、ADR-0021、ADR-0109、ADR-0112、ADR-0116、ADR-0117

背景

ADR-0117 已能认证上传 Artifact 并原子完成远端 Run，但 package Worker 在进程启动后没有持续的 Run Lease 控制链。只依赖 Offer 初始 expiry 会让长任务必然失租；只在 Worker 内存启动 timeout timer，则重启、休眠或时钟漂移后无法证明何时应停止。控制面若直接停止远端 PID，又会跨越节点 边界并可能误杀复用身份。取消、timeout、Session replacement 与 completion 还会竞争同一 Lease version，必须由一个完整 fence 和一个持久化顺序收敛。

低配路由设备不能为每个 Run 建 timer/socket；集群节点又需要多 Worker 实例和多 control replica 安全并行。因此控制协议必须是 caller-driven、有界、可重放，并保持数据库和本地进程各自唯一 authority。

决策

1. 不新增 package，新增 exact lease-control subpath

wire contract 放在 @qinglong/runtime-core/remote-worker-lease-control，Cluster service、PostgreSQL repository 和 Worker adapter 分别放入既有 cluster-control、cluster-postgres、worker-runtime。它们 没有新的依赖、部署、权限或发布责任，不满足 D-85 的拆包条件。

qinglong/remote-worker-lease-control@v1 request 最大 8 KiB，response 最大 4 KiB。Worker/Session 来自 path，body 携带 worker generation、Project、Run、Attempt、Offer、Lease generation、raw token 和 expected version。response 固定为 renewed、stop_requested 或 terminal，不回显 raw token 或 digest；续租响应必须恰为 expected version + 1。

Worker adapter 复用 ADR-0112 的 TLS 1.3 mTLS client、credential provider 和单 keep-alive Agent， 不创建第二个 socket authority。path/body identity、schema、byte cap、response authority 或 version 漂移全部 fail closed，临时 response buffer 消费后清零。

2. PostgreSQL 拥有时间、timeout intent 和 Lease version

repository 在 Attempt advisory lock 后，依次锁定当前 Worker Session、Run/Attempt 与 Run Lease， 最后读取数据库时间。它复验 Session/generation、Project、Run/Attempt 状态、Offer、Lease generation、 token digest、expected version 与 expiry；raw token 不进入 SQL、Event 或错误。

live claimed|starting|running authority 每次把 Lease 和 Attempt version 同时加一，并用数据库时间 写 renewed/expiry。若已有 user/policy/shutdown/reconcile/timeout cancel intent，则同一事务仍先续租， 再返回 durable stop request，让 Worker 有时间停止并提交 completion。若 Attempt deadline 已到且尚无 cancel intent，事务先原子写 run.cancel_requested_at_ms/reason=timeout、Run version/Event sequence 和 server-ID run.cancel_requested Event，再返回 stop request。已完整终态只做 exact terminal projection； 旧 Session、旧 version、过期 Lease 或状态漂移拒绝。

3. starting ACK 原子固定 durable deadline

timeout 只来自 Run 已 pin 的 immutable task_execution_revisions.plan_json.timeoutMs。starting ACK 在 既有 activation transaction 内 join 精确 Project/Task/task revision/executor revision，读取一次数据库 时间，并把 deadline_at_ms = observedAtMs + timeoutMs 与 Attempt starting 同时写入；Event 与 exact activation snapshot 投影同一 deadline。无 timeout 的 revision 必须保持 deadline 为 null。

Worker Processor 对 activation snapshot 做双向约束：revision 有 timeout 时 deadline 必须存在，revision 无 timeout 时 deadline 必须缺失。spawn 前再次 replay starting ACK；只有拿到 durable deadline 才把 timeoutMs + executionDeadlineAtMs 交给 Executor。Executor 对单边字段、负值或非安全整数 fail closed， 不再使用本地 timer 冒充控制面 timeout authority。

4. Worker 先回放 completion，再续租或精确停机

WorkerRemoteExecutionControlCoordinator.reconcile(offerId) 是单项、无 timer、同 Offer coalesced 操作：

1. 读取并规范化唯一 inbox record；已 completion ACK 直接结束。
2. 先调用 receipt-first completion recovery。Artifact/completion transport 临时失败与 lease transport 隔离，不能阻止仍运行进程保有 authority。
3. 本地 Lease 已到期时不再访问控制面，只对已持久化 durable handle 调用受审 LocalProcessController.stop()；TERM/KILL 成功或已退出记录 lease_lost_local_execution_stopped，身份/信号无法确认记录 lease_lost_local_execution_unverified。
4. Session 与本地 Lease 仍有效时发送完整 fence。renewed|stop_requested 必须先以 inbox revision CAS 持久化新 Lease version/time，再执行 stop；这样 completion 永远使用最新 version。
5. terminal 先停止精确本地身份，再将 record 隔离为 control_plane_terminal，绝不由旧 Worker 写控制面假终态。

5. Headless lifecycle 只做 caller-driven 有界监督

显式 headless lifecycle 现在要求注入 control coordinator。startup reconciliation 完成后，每个 tick 先按稳定 cursor 扫描最多 1–64 条 inbox record，串行监督 launching|started|running_acknowledged，再 决定是否 Pull。出现 lease loss、control-plane terminal 或 durable recovery fact 后立即停止 Pull。 监督扫描与 Pull 之间再次检查 AbortSignal，确保 shutdown 先中止请求再释放 journal owner。

lifecycle 不创建 timer、watcher、队列或额外连接。Edge 可以由外层单 cadence 使用较小 page，Node 可以增大到 64 或按 Worker 实例水平扩展；禁用时仍为零后台活动。外层 heartbeat/drain、共享 Artifact store 和完整 Worker Profile composition 未闭合前不得默认启用。

6. 用户取消使用认证 mutation 与事务内 Policy fence

Cluster Control 提供 POST /api/v3/projects/{projectId}/runs/{runId}/cancellation，权限固定为 run.stop。body 只接受 exact qinglong/run-cancellation@v1 与 bounded mutationId，reason 固定为 user，调用方不能伪造 shutdown|policy|timeout。通用 admission 必须在读 body 前完成 authentication、Project Policy 和 durable security audit；Agent 的 run.stop 仍返回 require_approval，不能用该路由绕过 Approval 状态机。

PostgreSQL repository 不能只信任 admission 的历史 allow：它在 serializable 短事务中依次锁定 Project、读取当前 RoleBinding、锁 Run，精确复验 Project/binding version、active 状态和 owner/admin/operator role。随后以数据库时间写 cancel_requested_at_ms/reason=user，递增 Run version/event sequence，并追加 server-ID、actor-bound run.cancel_requested Event。首次提交返回 202 accepted；已有意图和终态分别返回 200 already_requested|already_terminal，不重复 Event。 Project 漂移、撤权或角色变化在 Run 写入前返回 fence conflict；跨 Project 与不存在 Run 同样投影 404，避免资源枚举。该入口只提交 durable intent，不承诺进程已经停止；Remote Worker 在下一次 lease-control 看到 stop request。ADR-0119 已把该 mutation 固定注册进受审生产 registry；Worker ingress 与 headless 组合仍保持独立、默认关闭。

7. 非执行状态由一个有界 convergence lifecycle 收敛

ClusterRunCancellationConvergenceCoordinator 每周期最多处理 1–128 条、最多 1–64 页，跨调用 coalesce，自身不持有 timer、连接或队列。Cluster Control 外层只创建一个全局 cadence；Edge/Standalone 后续也可复用 coordinator 并选择更小预算，不得创建 per-Run timer。

PostgreSQL repository 用 FOR UPDATE SKIP LOCKED 在短事务内选择已经有 durable cancel intent 且处于 created|queued|waiting_approval|retry_wait|lost 的 runtime Run。lost 不是终态，因为 retry authority 仍可把它推进 retry_wait|queued；取消 API 不得提前返回 already_terminal。最新 Attempt 若仍是 claimed，repository 先把 Attempt 收敛为 cancelled|timed_out，随后按连续 sequence/version 原子终结 Run 并写两条 reconciler Event；没有活动 Attempt 或最新 Attempt 已终态时只写 Run Event。

Event ID 只在实际锁到 candidate 后，按 domain + Run/Attempt + cancel timestamp 做域分离 SHA-256 并截取 128 bit，空闲 tick 不预生成 UUID；同一次意图重试得到同一稳定 ID。若发现已经跨过 start barrier 的 starting|running Attempt 或带 active Lease 的 claimed Attempt，repository 返回 blocked，绝不伪造 终态；这些状态只允许由 Worker completion 或受信 evidence recovery 收敛。多 replica 通过 SKIP LOCKED 分摊候选，无需新增 claim 表、migration、schema 或常驻连接。

被否决的替代方案

1. 每 Run 一个 timeout/renewal timer：资源随并发增长，休眠与重启丢失语义，拒绝。
2. Worker 本地时钟决定 durable timeout：多节点时钟漂移且不能认证重放，拒绝。
3. 控制面远程发送 PID signal：跨节点 authority 且 PID 可复用，拒绝。
4. stop 后再保存 Lease version：完成回调会携带旧 version，被 fence 或产生不可解释窗口，拒绝。
5. 续租失败立即写 Run lost：旧 Worker 无控制面终态写 authority，拒绝。
6. 为 lease client/coordinator 新建 package：依赖与发布责任未分离，违反 D-85，拒绝。
7. 只在 admission 检查一次 Policy：授权与 Run mutation 之间可被撤权竞态穿透，拒绝。
8. 允许调用方提交 cancel reason：可伪造系统 shutdown、policy 或 timeout 事实，拒绝。

验收证据

1. runtime exact wire 覆盖 renewed/stop/terminal、byte cap、未知字段和非法 shape。
2. ingress 先认证/audit，再 path-bind command；fenced 映射 409、storage unavailable 映射 503，response 不泄漏 token。
3. PostgreSQL repository 覆盖续租、既有取消、deadline timeout intent、terminal projection、旧 version rollback，且 raw token 不进入 SQL/Event。
4. starting ACK 用数据库时间写 deadline，无 timeout 时写 null；wire round-trip deadline。
5. Worker HTTPS adapter 验证完整 identity 和 version + 1；真实 TLS 1.3 mTLS 回归在同一默认 Agent 上连续执行 Artifact、completion 与 lease-control，并验证可清零凭据 Buffer 不会改变 socket 回收池键或挂起后续请求。
6. control coordinator 证明 completion-first、persist-before-stop、本地过期不访问控制面、成功/不确定 stop 证据分离、Session unavailable 和同 Offer coalescing。
7. headless lifecycle 证明 bounded supervise-before-Pull、recovery fail-closed、tick coalescing 与 Abort-before-release。
8. Executor 无 durable deadline 时不 spawn，有 deadline 时通过原有 reviewed spawn barrier。
9. exact 用户取消 route 在 admission 后传递完整 subject/policy fence；PostgreSQL 16 最小权限 runtime role 真实验证 accepted、exact replay、Event actor/payload 与撤权 fence rejection。
10. 未新增 workspace package、migration、schema、per-run timer、队列或常驻连接。
11. bounded convergence 覆盖 queued+claimed、lost+terminal Attempt、timeout、blocked start barrier、 page/coalescing/stop drain；PostgreSQL 16 最小权限 runtime role 真实验证 run.cancel_requested → attempt.cancelled → run.cancelled 原子序列。
12. ADR-0125 的本机 arm64 PostgreSQL 18.4 physical-promotion 门分别在用户 cancellation intent 和 cancellation convergence 的 driver-confirmed COMMIT 后终止 transaction backend。意图以同一 command 重放为 already_requested，终态收敛重放扫描 0 条；standby 在 promotion 前及 timeline 2 promoted primary 上均保持 Run version 4/event sequence 3、上述 3 条 Event、3 个 dedupe key 和 0 duplicate。故障范围是 PostgresClient 边界，不是 raw-wire packet-loss。