docs: clarify AgentRun session resume boundaries

docs/reference/agentrun-code-agent-dispatch.md

@@ -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`。