docs: clarify AgentRun session resume boundaries

2026-06-04 01:02:12 +08:00
parent ac0a7e57d8
commit f81aad7ace
4 changed files with 26 additions and 5 deletions
@@ -9,6 +9,18 @@
 - `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager；调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。
 - 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`，默认 providerId 是 `G14`，默认 workspace branch 是 `v0.2`。

+## 会话和执行边界
+
+- HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authority；AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identity；AgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session，也不要把复用 workspace selection 当作 session state。
+- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。
+- `providerProfile` 由显式 HWLAB session 负责。`client agent session create --provider-profile <profile>` 建立 session 的 provider profile，并映射为 AgentRun `backendProfile`；后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时必须继承该 session 的 `providerProfile`。账号 workspace 的 provider profile 只在 workspace 当前 selected session 与本次目标 session 完全一致时作为 fallback；旧 workspace 状态不得覆盖显式 session。
+- 同一 HWLAB session 的 resume 判定看同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC，而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job，但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时，才算 session 持久化恢复证据；它不替代 runner reuse window 内复用同一 run/runner 的长期目标。
+
+## 架构混乱处理
+
+- 临时处理：排查 CLI/Web/Cloud API/AgentRun 对 session、project、provider 或 run/job 的口径不一致时，先收集 HWLAB session status、workspace selection、trace/result、AgentRun run/job env、`SessionRef`、PVC phase 和 command events；以单变量热补丁证明最小链路，再回到源码 PR/CI/CD/原入口复测。不得通过长 prompt、历史 messages、fake `thread/resume:completed`、放宽 tenant policy 或手工改 DB lease 来掩盖缺口。
+- 长期建议：跨仓库 schema 必须把 `hwlabProjectId` / `agentRunProjectId`、`providerProfile` / `backendProfile`、`hwlabSessionId` / `agentRunSessionId`、`runId` / `sessionId` 分成不同字段；Web 和 CLI 应同时展示业务 session/thread/provider 与执行 run/job/command，避免 operator 把执行尝试误判为业务会话迁移。
+
 ## Credential 边界

 - Provider credential 只通过 `executionPolicy.secretScope.providerCredentials[]` 的 AgentRun provider SecretRef 引用，默认随 `backendProfile` 选择 `agentrun-v01-provider-deepseek`、`agentrun-v01-provider-codex` 或 `agentrun-v01-provider-minimax-m3`。
@@ -18,11 +18,12 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb

 - 无 Code Agent session 时，必须先显式创建 session，再发送 turn。CLI 目标入口为 `client agent session create`；Web 目标入口为“新建 session”显式动作；Cloud API 目标入口为 `POST /v1/agent/sessions`。session 创建返回 `conversationId/sessionId`，`threadId` 可以在首轮 turn 被 provider/AgentRun 建立后回写。
 - `client agent session create|select|status` 的默认 JSON 输出必须在顶层直接暴露 `sessionId`、`conversationId`、`threadId`、`providerProfile`、`sessionStatus` 和 `sessionUsable` 这类短连接脚本高频字段；完整原始响应仍保留在 `session` 或 `body` 中。人工和 agent 不应为了拿 sessionId 手写一次性 JSON 深挖脚本，也不应依赖 `sed`/`grep` 解析 JSON。
+- 显式 session 是 provider profile authority。`client agent session create --provider-profile <profile>` 创建的 session 后，`client agent send --session-id <sessionId>` 在未传 `--provider-profile` 时必须先读取该 session 并继承 `providerProfile`；显式 `--provider-profile` 只作为人工有意覆盖，必须在输出和 trace 中可见。workspace provider profile 只能在 workspace selected session 与本次目标 session 完全一致时作为 fallback，不能用旧 workspace 状态覆盖显式 session。
 - `client agent send` 必须携带显式 `--session-id`，或使用此前通过 `client agent session create|select` 明确选中的 workspace session；没有显式或已选 session 时返回结构化 `session_required`，不能自动生成 `conversationId/sessionId/threadId`。
 - 显式传入新的 `--conversation-id` 时，如果没有同时显式 `--session-id` 或 `--from-trace` 恢复出的 session，CLI 不得从账号 workspace 继承旧 session；这种情况必须返回 `session_required`，提示先为该 conversation 创建或选择 session。只有显式 conversation 与 workspace 当前 conversation 完全一致时，才允许使用 workspace 中已显式选中的 session。
 - session 失败、`thread-resume-failed`、provider continuation 失效、用户取消或运行面中断时，当前 session 必须保留为 failed/stale/canceled 证据；系统不得自动滚动到新 session、不得隐式清理后继续，也不得把下一条普通消息路由到新 session。继续工作前必须显式创建或选择另一个 session。
 - `--from-trace` 只用于 inspect 和显式复现 trace 所属 session；如果 trace 所属 session 已失败或 stale，CLI/Web/API 必须返回该失败 session 的证据和“请显式创建新 session”建议，不能自动替换 continuation。
- 最终 CLI 交互验收必须使用 HWLAB CLI 原入口，并按“登录 -> 显式创建或选择 session -> `client agent send --session-id ... --provider-profile minimax-m3 --message "在吗?"` -> result/trace”的顺序执行；不得用 UniDesk CLI 包装测试，也不得用 fresh auto session 掩盖失败 session 问题。
+- 最终 CLI 交互验收必须使用 HWLAB CLI 原入口，并按“登录 -> 显式创建或选择 session -> 至少一次 `client agent send --session-id ... --message "在吗?"` 不传 `--provider-profile` -> result/trace”的顺序执行，证明 send 继承显式 session 的 provider profile；MiniMax-M3 验收应先在 `session create` 传 `--provider-profile minimax-m3`。不得用 UniDesk CLI 包装测试，也不得用 fresh auto session 掩盖失败 session 问题。

 ## 在系统中的职责划分

@@ -46,6 +47,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
 - `client agent composer status|submit` 是 Cloud Web composer 的状态机等价入口。`status` 必须先恢复账号 workspace，再输出 `sessionRequired`、`sessionUsable`、`submitMode`、`route`、`targetTraceId`、conversation/session/thread 和 workspace revision；没有已选 session 时必须显示 `sessionRequired=true`。`submit` 只能在已显式选中可用 session 时提交 turn；运行中 trace 的 steer 仍走同源 `/v1/agent/chat/steer`，但不能借 steer/turn policy 自动创建或滚动 session。
 - Code Agent continuation 的 thread 字段只有 `threadId` 一个标准名称。CLI 读取 inspect、`--from-trace` 回放、手动 `--thread-id` 提交和输出摘要都必须以该字段为唯一 thread identity；服务端响应也应保持同一字段口径。
 - `client agent send` 可以恢复账号 workspace 来读取“已显式选中”的 session，但 workspace 只代表 selection，不代表自动创建或自动恢复。`send` 只发送该 session 的 `conversationId/sessionId/threadId`、`workspaceId` 和 `expectedWorkspaceRevision`；终态轮询后 PATCH workspace 只能更新 session 状态、active trace 和 evidence。默认 workspace 恢复不恢复 messages/facts，不生成 `conversationContext`，也不得把历史文本拼入 prompt。显式传入新的 `--conversation-id` 不能隐式继承旧 session/thread，CLI 层应在发出 `/v1/agent/chat` 前返回 `session_required`；需要新 session 时必须先 `client agent session create --conversation-id <ID>`。
+- 架构混乱排查时，CLI 输出必须把 `sessionId`、`conversationId`、`threadId`、`providerProfile`、`runtimeEndpoint`、`traceId`、`runId`、`commandId` 和 `jobName` 分开显示。临时处理以显式 session status、AgentRun run/job env、`SessionRef` 和 PVC phase 为证据；长期收敛见 [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md) 的会话和执行边界。
 - `client agent steer <traceId>` 是运行中引导入口，必须调用 Cloud Web 同源 `POST /v1/agent/chat/steer`，把 steer 文本装配成 AgentRun `type=steer` command 作用到目标 trace 的 active turn。CLI 不手动穿内部 URL；验收使用当前 runtime namespace/lane 自动解析的 `19666` Web 入口，并通过原 trace 的 result/trace 观察 steer 是否被 runner 接收和应用。
 - `client agent trace <traceId> --render web` 必须调用 Cloud Web trace row 的同一纯转换路径，输出 `render="web"`、renderer 标识、source event count、rendered row count、默认压制的 noise event count 和 row 摘要。浏览器 trace 展示错乱时，必须先用该 CLI 入口确认 Web 渲染转换是否已经乱序、重复、缺 final response、吞掉关键 row 或只显示泛化 tool call，再继续修浏览器 DOM/CSS。
 - AgentRun v0.1 短连接 runner 已要求支持同 run/runner 多轮 command。CLI 仍应把 Web 提交的 `conversationId/sessionId/threadId` 原样送到 Cloud Web API，用于验证 adapter 是否在 runner reuse window 有效时复用同一个 AgentRun `runId` / `jobName` 并创建新 `commandId`；每轮都新建 runner 或重新 bundle 不是通过状态，trace 中的原因说明只能用于定位。
@@ -107,7 +109,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb

 ## T3

-阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：先运行 `client agent session create --provider-profile minimax-m3` 显式创建 session，再运行 `client agent send --session-id <sessionId> --message "在吗?" --provider-profile minimax-m3 --wait --timeout-ms 120000`，确认响应包含 accepted/result/trace 信息和 assistant 回复文本。未先创建或选择 session 时，`client agent send --message "在吗?"` 必须返回结构化 `session_required`，不能自动创建 session。该验收默认使用 MiniMax-M3；如果是 DeepSeek 专项才切换 provider profile。
+阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：先运行 `client agent session create --provider-profile minimax-m3` 显式创建 session，再运行 `client agent send --session-id <sessionId> --message "在吗?" --wait --timeout-ms 120000`，确认 send 未传 `--provider-profile` 也继承 session 的 `providerProfile=minimax-m3`，响应包含 accepted/result/trace 信息和 assistant 回复文本。未先创建或选择 session 时，`client agent send --message "在吗?"` 必须返回结构化 `session_required`，不能自动创建 session。该验收默认使用 MiniMax-M3；如果是 DeepSeek 专项才切换 provider profile。

 ## T3.1

@@ -15,12 +15,15 @@
 - `internal/cloud/access-control.ts` 负责 `/auth/*`、OIDC callback、Web session、用户 API key、admin/user、device pod profile/grant、device job lifecycle 和 Code Agent owner binding；登录与鉴权 authority 见 [spec-v02-auth.md](spec-v02-auth.md)。当前本地 `/auth/login` 只作为 bootstrap/legacy fallback。
 - `internal/cloud/access-control.ts` 也是账号 workspace authority：`account_workspaces` 记录同一账号的 Workbench 当前 workspace、selected conversation/session、active trace、provider profile 和 revision。
 - Code Agent session 生命周期必须显式化。Cloud API 目标入口为 `POST /v1/agent/sessions` 创建 session、`GET/PATCH /v1/agent/sessions*` 查询/选择/标记状态；`POST /v1/agent/chat` 只接受显式传入或账号 workspace 中已显式选中的 usable session。没有 session 时返回 `session_required`，session failed/stale/canceled 时返回 `session_not_usable`，不得自动创建、滚动或替换 session。
+- Code Agent session record 是 provider profile authority。`POST /v1/agent/chat` 带显式 session 且请求未显式给出 provider profile 时，Cloud API 必须继承该 session 的 `providerProfile` 并映射为 AgentRun `backendProfile`；请求显式覆盖 provider profile 时，覆盖必须进入 trace/result 可见字段。账号 workspace 的 provider profile 只能在 selected session 与目标 session 完全一致时作为 fallback，不得让旧 workspace 覆盖显式 session。
 - `internal/db/runtime-store.ts` 和 `internal/cloud/db-contract.ts` 负责 Postgres runtime store 与 readiness 分层。
 - `internal/cloud/code-agent-*.ts` 负责 Codex stdio session、trace store、result cache、provider profile 和取消/轮询。
+- AgentRun dispatch 的 policy 字段由 Cloud API adapter 固定归一化：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。Workbench project/workspace 只能作为 HWLAB metadata 或 `workspaceRef` 子字段保存，不能污染 AgentRun `projectId`；出现 project/tenant 混乱时，临时处理是修 adapter 字段映射并用真实运行面最小请求复测，不放宽 AgentRun manager policy。
 - AgentRun v0.1 接入只使用标准 `threadId` 路径：`POST /v1/agent/chat` 收到的 `conversationId/sessionId/threadId` 必须写入 AgentRun command `payload.threadId` 和 `SessionRef.threadId`；协议字段、trace、result 和 conversation facts 都以该字段为唯一 thread identity。
 - AgentRun run 级 events 写回 HWLAB trace 时必须按当前 `commandId` 归属过滤；同一 run 的旧 command 尾部事件不能混入后续 command trace。取消、失败或 blocked 轮次如果已有 assistant/tool 可读进展，必须以脱敏、限长的 conversation facts 写入 UI/trace/inspect 证据，供后续 `inspect`/`--from-trace` 可见性使用；这些 facts 不得作为下一轮模型上下文或 prompt 拼接来源。
 - AgentRun completed 轮次续接必须依赖 Codex stdio 原生 session continuation。Cloud API 只把本轮原始 `message/prompt` 和显式 session 的标准 `conversationId/sessionId/threadId` 写入 AgentRun command payload 与 `SessionRef`；不得从请求、account workspace 或 account conversation 生成 `conversationContext`，不得把历史消息拼入 prompt，也不得把请求体里的 `conversationContext/messages` 当作模型上下文。历史 conversation facts 只用于 UI、inspect、trace 和 `--from-trace` 的可见性证据；收到 synthetic context 字段时只能记录 ignored trace 并剥离。`thread/resume` 失败时按 AgentRun `thread-resume-failed` 终止本轮并标记当前 session failed/stale，不自动创建新 session。
 - Code Agent 不允许存在 turn/session/conversation 总时长 timeout；只允许无新 app-server 响应、无 notification、无 assistant/tool/event activity 的 idle timeout。AgentRun command 失败、provider 失败或 idle timeout 只终结当前 command，并按 session policy 标记当前 session 状态；系统不得自动滚动到新 session。后续消息要么继续同一个 usable session/thread，要么由用户显式创建或选择另一个 session。
+- runner pod 被删、runner Job 被重建或旧 lease 失效后，同一 HWLAB session 的恢复判定必须基于同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC。replacement run/job 只能作为恢复执行壳；Cloud API 仍要把它映射为同一业务 session 的后续 turn，并在 trace/result 中分离业务 session identity 与执行 run/job identity。长期目标仍是在 runner reuse window 内复用同一 AgentRun run/runner。
 - Cloud API 通过 AgentRun v0.1 `runner-jobs.transientEnv` 传递本次 Code Agent turn 的短期上下文，例如 `HWLAB_RUNTIME_*`、`HWLAB_CODE_AGENT_ASSEMBLED_RUNTIME` 和 `HWLAB_DEVICE_POD_API_KEY`。`transientEnv` 不设固定 8 项上限，新增短期上下文时必须按 name 去重、只传本次 Job 需要的 value；`HWLAB_RUNTIME_API_URL` 必须指向当前 namespace 内的 `hwlab-cloud-api` Service，`HWLAB_RUNTIME_WEB_URL` 才指向 `hwlab-cloud-web`；`HWLAB_DEVICE_POD_API_KEY` 只能作为 assembled runner 内 `hwpod` 访问正式 device-pod 的统一授权，必须标记 sensitive，并继续禁止承载 GitHub token、provider key、长期 SSH key 或其他可复用 credential；文档、日志和 trace 只允许保留脱敏后的 name、来源或摘要，不打印 Secret 值。
 - 同 Pod sidecar `hwlab-codex-api-forwarder` 监听 `127.0.0.1:49280/responses`，用于 `codex-api` profile 直连 hyueapi，并保持 hyueapi 在 `NO_PROXY` 中。
 - `hwlab-code-agent-workspace` PVC 挂载到 `/workspace/hwlab`，用于长会话 workspace；它是 cloud-api 运行资源，不是独立用户入口。
@@ -13,10 +13,12 @@
 - Cloud Web 只承担浏览器 UI 和 `hwlab-cli client` 的同源代理。AgentRun runner 内的 `hwpod` 不走 Cloud Web；Cloud Web 不转发 AgentRun Device Pod API key，也不保留 device-pod lease 路由。
 - 浏览器启动后必须从 `GET /v1/workbench/workspace` hydrate 账号 workspace；同一个账号在多个浏览器标签页、多个浏览器或 CLI profile 中应看到同一个 `workspaceId`、selected conversation/session/thread、provider profile 和 active trace。浏览器 localStorage 只能作为短期缓存，并必须绑定 actor，不能作为 workspace authority。
 - Code Agent session 管理必须全部手动化。Workbench 可以从账号 workspace 恢复“已显式选中”的 session，但不能在普通发送、页面刷新、trace replay、失败恢复或 provider resume 失败时自动创建、滚动或替换 session。没有已选 session 时，composer 必须展示“新建 session/选择 session”的显式动作；session failed/stale/canceled 后必须保留失败证据，继续前由用户显式新建或选择另一个 session。
+- 显式 session 的 `providerProfile` 优先于账号 workspace provider profile。Workbench 可以展示 workspace 默认 provider，但对已选 session 发送 turn 时必须使用该 session 的 provider profile；用户想切换 provider 时，应显式创建或选择对应 provider 的 session，不能把旧 workspace provider 静默套到当前 session 上。
 - Cloud Web trace 展示与 `hwlab-cli client agent trace --render web` 必须共享同一套 trace row 纯转换路径。Web 发生 row 顺序错乱、final response 缺失、assistant 消息被吞、tool call 只显示泛化占位或噪声事件淹没时，先用 CLI 输出同一渲染 row 摘要和 noise event count 复现；CLI 可复现说明是 trace row 转换问题，CLI 不可复现再进入 DOM/CSS/滚动状态调查。默认展示应压制 AgentRun backend echo、token/rate-limit/status/terminal echo 等低价值事件，但原始 trace JSON 仍必须保留用于 `--full`/下载排障。
 - Cloud Web Code Agent composer 必须无锁：运行中 turn 不得把输入框或发送按钮 disabled。浏览器提交时必须基于已显式选中的 session 工作；没有 session 时返回 `session_required` 并引导用户新建 session，不能自动开 session。存在 active running trace 时，用户显式 steer 动作走 `POST /v1/agent/chat/steer`；空闲且 session usable 时，用户显式发送 turn 走 `POST /v1/agent/chat`。`hwlab-cli client agent composer status` 必须能用同一 policy 输出 `sessionRequired`、`sessionUsable`、`submitMode=turn|steer`、`route` 和 `targetTraceId`。
 - Code Agent result `completed` 只有在同时包含真实 provider/model/trace/conversation 元数据、`providerTrace` 和可展示的 final assistant response 时，才能被 Web 标记为真实完成；`provider=agentrun-v01` 只是执行基础设施标识，不得替代上游 provider/model，也不得把 SOURCE、fixture、echo、mock 或 stub 当成 DEV-LIVE 完成。
 - 同一显式 conversation/session 的后续用户消息必须在 AgentRun runner reuse window 有效时复用已存在的 AgentRun run/runner 继续新 command/turn；只有 runner 不可用、已过期或用户显式创建新 session 时才重新 bundle 和启动 runner。每条消息都重新 bundle/runner 属于 v0.2 AgentRun 接入缺口，不能只靠 trace 显示原因当成已完成。
+- runner pod 被删、runner Job 重建或旧 lease 失效后的临时恢复，可以显示新的 AgentRun run/job/command identity，但 Web 必须继续以同一个 HWLAB `sessionId` / `threadId` / provider profile 呈现业务会话，并明确区分“同 session 恢复执行壳”和“新业务 session”。只要复用同一 AgentRun `SessionRef`/PVC/thread 且没有拼接历史 prompt，replacement run/job 可以作为 session 持久化恢复证据；它不替代 T2.2 的同 run/runner reuse 目标。
 - AgentRun 会话连续性只有一个标准路径：Cloud Web/CLI 提交的 `threadId` 必须经 Cloud API adapter 写入 AgentRun command `payload.threadId` 和 `SessionRef.threadId`。前端、CLI、API 和 AgentRun 的协议字段、trace、result 和 conversation facts 都以该字段为唯一 thread identity。
 - Cloud Web 提交 Code Agent turn 时只发送当前用户消息、共享 workspace 的 `conversationId/sessionId/threadId`、workspace revision 和必要运行元数据；不得发送 `conversationContext/messages`，也不得把浏览器历史拼入 prompt。历史消息只用于本地 UI 展示和 trace/inspect 可见性，不能替代 AgentRun/Codex stdio 原生 `thread/resume`。
 - Workbench 不允许把 Code Agent 长任务总耗时当成失败条件；只能在无新 trace/event/activity 的 idle timeout 后显示超时。AgentRun command/provider/backend 失败后，当前消息可显示 failed/blocker；session 是否仍 usable 必须由 session 状态显式表达。`thread-resume-failed`、provider continuation 失效、运行面中断或用户取消导致 session failed/stale/canceled 时，不得自动清理并滚动到新 session；继续前必须由用户显式创建或选择 session。
@@ -73,7 +75,7 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验，

 ## T2.2

-阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先显式创建 session，再在同一 conversation/session 连续发送两条 Code Agent 消息，确认第二条复用第一条的 AgentRun `runId` 和 runner `jobName`、生成新的 `commandId`，且不重新 materialize bundle/启动新 runner；result completed 必须包含真实 provider/model/`providerTrace`/trace/conversation 和 final assistant response。复用失败原因只能作为诊断，不作为本测试通过条件；如果 session failed/stale，必须显式创建新 session 再继续。
+阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先显式创建 session，再在同一 conversation/session 连续发送两条 Code Agent 消息，确认第二条复用第一条的 AgentRun `runId` 和 runner `jobName`、生成新的 `commandId`，且不重新 materialize bundle/启动新 runner；result completed 必须包含真实 provider/model/`providerTrace`/trace/conversation 和 final assistant response。复用失败原因只能作为诊断，不作为本测试通过条件；如果 runner pod 已被删除或旧 lease 已失效，replacement run/job 只能作为同 session/PVC/thread 的恢复证据记录，不能算作本测试的 run/runner reuse 通过。如果 session failed/stale，必须显式创建新 session 再继续。

 ## T2.3

@@ -99,6 +101,8 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验，

 HWLAB v0.2 Code Agent chat turn 默认走 `sessionStorage=persistent`：每次 turn 由 `code-agent-agentrun-adapter.ts` 在创建 run 之前显式调 `POST /api/v1/sessions`，让 AgentRun v0.1 同步创建 RWO PVC（`agentrun-v01-session-<sessionId>`，1Gi，StorageClass 走 env `AGENTRUN_SESSION_STORAGE_CLASS` 默认 `local-path`）。runner Job manifest 渲染时多挂一个 `agentrun-sessions` volume + `AGENTRUN_SESSION_PVC_NAME` / `_NAMESPACE` / `_MOUNT_PATH` / `AGENTRUN_CODEX_ROLLOUT_SUBDIR` env，使 codex app-server 自己把 rollout JSONL 写进 PVC，跨 runner pod 重建天然 `thread/resume:completed`。

+runner pod 或 runner Job 丢失但 PVC 仍存在时，下一轮必须继续使用同一个 HWLAB `sessionId`、标准 `threadId`、session provider profile 和 AgentRun `SessionRef`/PVC 执行 resume。当前临时恢复允许 Cloud API 启动 replacement run/job 作为执行壳；验收必须记录 replacement run/job 与原业务 session 的对应关系，并证明没有通过历史 prompt、messages 或 fake resume 续接。长期目标仍是 runner reuse window 内同一 AgentRun run/runner 多 command。
+
 ### Eviction reset UX

 当 AgentRun v0.1 上报 `failureKind=session-store-evicted`（PVC 被删或 TTL 到期）时，HWLAB cloud-api 走 reset UX：
@@ -118,9 +122,9 @@ HWLAB v0.2 Code Agent chat turn 默认走 `sessionStorage=persistent`：每次 t
 | 规格项 | 状态 | 说明 |
 | --- | --- | --- |
 | 调 POST /api/v1/sessions 同步建 session + PVC | 已实现 | `code-agent-agentrun-adapter.ts::ensureAgentRunSessionPersistent` 默认 `sessionStorage=persistent`；env `HWLAB_CODE_AGENT_AGENTRUN_SESSION_STORAGE=ephemeral` 可退回 metadata-only 模式。 |
-| runner Job 直接挂载 PVC | 已实现（agentrun-v01 侧 PR A/B/C 已上线） | HWLAB 侧无需额外代码，runner Job manifest 由 AgentRun v0.1 渲染。 |
+| runner Job 直接挂载 PVC | 已实现/已通过 HWLAB v0.2 原入口复测 | runner Job manifest 由 AgentRun v0.1 渲染 per-session PVC 直接挂载；HWLAB 侧以同 session/thread/PVC resume 作为恢复证据，不走 copy/restore。 |
 | eviction reset UX | 已实现 | submitAgentRunChatTurn 走两步尝试，第一步在 ensureSession 或 runner-jobs POST 收到 `session-store-evicted` 时用新 sessionId + `threadId=null` 重试。 |
-| UX 错误码 `session_storage_evicted` | 待 PR D 收口 | `code-agent-response-contract.mjs` 把 `session-store-evicted` 归 `session-blocked`；`code-agent-chat.ts` 加 userMessage。 |
+| UX 错误码 `session_storage_evicted` | 目标状态/需专项复测 | `session-store-evicted` 必须归入 `session-blocked`，并向用户区分“PVC 被回收，需要新 session”与普通 provider/backend 失败；不能用 fake resume 或自动无感滚动掩盖。 |
 ## 规格的实现情况

 | 规格项 | 状态 | 说明 |