docs: clarify HWLAB session resume boundaries

This commit is contained in:
Codex
2026-06-04 01:02:12 +08:00
parent a3422b4c76
commit 2ebb51eed7
5 changed files with 26 additions and 12 deletions
+4 -3
View File
@@ -136,7 +136,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB
- events append-only,单 run 内 `seq` 单调递增。
- command terminal 与 run terminal 必须分离。普通 turn completed 只终结对应 commandrun 可以保持 `claimed/running` 以继续接收后续 command;每个 command result 必须能从 command record 与 command-scoped events 得到 authoritative terminal。run 级 `terminal_status` 只用于 run cancel、runner 级不可恢复失败或明确 run terminalassistant partial、stdout、transport close 或 idle timeout 不能替代 terminal completed。
- failureKind 至少能区分 `schema-invalid``tenant-policy-denied``secret-unavailable``runner-lease-conflict``backend-failed``provider-auth-failed``provider-unavailable``infra-failed``cancelled`
- failureKind 至少能区分 `schema-invalid``tenant-policy-denied``secret-unavailable``runner-lease-conflict``backend-failed``provider-auth-failed``provider-unavailable``infra-failed``cancelled``runner-lease-conflict` 对普通并发 runner 是拒绝原因;对 replacement runner 是可恢复的 transient 状态,manager 响应必须包含当前 owner、lease expiry 或等价等待依据,便于 runner 等待 stale lease 并重试。
- health/readiness 必须返回 Postgres reachable、schema migration ready、SecretRef redacted 状态和 build/source metadata。
- 日志、event、trace、health 和 diagnostics 不得输出 provider credential、Codex auth/config 内容、DSN password、token 或 URL credential。
@@ -175,7 +175,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB
### T4 Runner claim 与 event pagination
阅读本文和 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md),然后让两个真实 runner 尝试 claim 同一个 run。确认只有一个 owner 成功,另一个返回 `runner-lease-conflict` 或等价 failureKind;随后分页读取 events,确认 `seq` 单调、不重复、不丢失。
阅读本文和 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md),然后让两个真实 runner 尝试 claim 同一个 run。确认只有一个 owner 成功,另一个返回 `runner-lease-conflict` 或等价 failureKind,并包含足够判断 owner/lease expiry 的结构化字段;随后分页读取 events,确认 `seq` 单调、不重复、不丢失。再模拟旧 runner pod 删除后的 replacement runner,确认旧 lease 过期后 replacement runner 可以接管,且 claim waiting/recovered 事件可见。
### T5 手动 runner Job 调度 API
@@ -197,7 +197,8 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB
| command/run terminal 分离 | 已实现最小闭环 | `PATCH /api/v1/commands/:commandId/status` 终结 command 并更新 SessionRef;普通 turn completed 不终结 runrun status 仅由 run cancel 或 runner 级不可恢复失败终结。 |
| Tenant policy boundary | 已实现最小边界 | v0.1 已做 schema、tenant/backend allowlist、executionPolicy 和 secretScope 结构校验;业务授权仍由 UniDesk/HWLAB 自己判定。 |
| `deepseek` backendProfile allowlist | 已实现/已通过主闭环 | Manager validation、backend capability 和 matching SecretRef 校验已支持 `deepseek`;真实 runtime 已经通过 CI/CD 发布并确认 Postgres migration `002_v01_backend_profiles` 应用。 |
| `minimax-m3` backendProfile allowlist | 已实现/待真实主闭环 | Manager validation、backend capability 和 matching SecretRef 校验已支持 `minimax-m3`;真实 runtime 需要通过 CI/CD 发布并完成 AgentRun CLI 手动验收。 |
| `minimax-m3` backendProfile allowlist | 已实现/已通过 HWLAB v0.2 原入口复测 | Manager validation、backend capability 和 matching SecretRef 校验已支持 `minimax-m3`;真实 runtime 通过 HWLAB 显式 session CLI 原入口复测。 |
| Postgres durable adapter | 已实现/已通过主闭环 | live runtime 通过 `DATABASE_URL` 使用 Postgres durable storememory store 仅用于显式 self-test/dev。见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
| Observability 最小合同 | 已实现主路径 | events append-only、command-scoped terminal status、failureKind、health/readiness store 状态、runner claim/lease/backend events 和 Secret/DSN redaction 已进入 manager;集中 trace 和部署级观测仍属后续工作。 |
| durable cancel API | 已实现最小闭环 | 已提供 run/command cancel APIpending command cancel 阻止新 runner Jobrunning runner 轮询 cancel 并中止 Codex stdio backend,终态使用 `cancelled`。 |
| stale lease recovery | 已实现/已通过 HWLAB v0.2 原入口复测 | replacement runner 遇到旧 lease 时等待 stale lease 并重试 claim,成功接管后继续同一 SessionRef/PVC/thread;正常并发 runner 仍返回 `runner-lease-conflict`。 |