docs: define temporal native CaseRun architecture

docs/MDTODO/details/hwlab-caserun/R4.1_Task_Report.md

@@ -0,0 +1,42 @@
+# R4.1 Temporal 与 native 服务合同报告
+
+## 结论
+
+已完成 CaseRun/HarnessRL Temporal 化与 native 敏捷开发的规格定锚。后续实现必须以 `draft-2026-07-17-p0-temporal-native-agile` 为 HarnessRL 实现引用版本。
+
+## 架构裁决
+
+- 拆分 `hwlab-harnessrl-api` 与 `hwlab-harnessrl-worker`。
+- Temporal workflow history 只拥有编排、retry、timer、signal、cancel 和恢复。
+- HarnessRL registry 复用 HWLAB 既有 PostgreSQL，拥有 run/read model、stage event、workflow identity、manifest 和 aggregate 索引。
+- AgentRun 继续拥有 run、command、session、trace 和 final。
+- HWPOD 继续拥有 lease、node route、operation result 和原始硬件事实。
+- Cloud Web、CLI 与 native fixture 都不得生产或推断业务成功事实。
+
+## Native 合同
+
+- 后端可在 Kubernetes 外独立启动 Temporal 开发运行时、API 和 worker。
+- API 与 worker 分别支持 watch/reload。
+- CLI 默认 local 模式，显式 `--over-api` 使用同源 HarnessRL API。
+- 两种 CLI 模式共享 application service、DTO、typed error 和 submit-and-poll。
+- 前端可独立启动 Vite HMR 与 native CaseRun test API。
+- native fixture 必须标记 `mode=native-test`，不得进入生产配置或 fallback。
+
+## 交付顺序
+
+1. Temporal 后端与 API/worker 分离。
+2. CLI 双模式。
+3. 前端 native 服务。
+4. native smoke，包括 cancel 和 API/worker restart recovery。
+5. 仅通过 `v0.3` PR merge 触发原 PaC/Tekton/GitOps/Argo 自动链回归。
+
+## 规格文件
+
+- `PJ2026-0103-harness-rl.md`
+- `PJ2026-010402-hwlab-cli.md`
+- `PJ2026-010401-web-workbench.md`
+
+## 执行入口
+
+- 主 issue：`pikasTech/HWLAB#2614`
+- MDTODO：`docs/MDTODO/hwlab-caserun.md` R4

docs/MDTODO/hwlab-caserun.md

@@ -59,3 +59,31 @@ P0 基线与合同设计：复核 merge-base、v0.2/v0.3 能力矩阵和 Harness
 ## R3 [completed]
 
 执行 [HWLAB #2580](https://github.com/pikasTech/HWLAB/issues/2580)：在 R1.5 合并后收敛 CaseRun 当前 39 个真实 scoped TypeScript finding，使 `hwlab-cli case audit` 对当前源码恢复通过；只做类型合同收敛与语义等价验证，不恢复错误码白名单或 v0.2 兼容，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R3_Task_Report.md)。
+
+## R4 [in_progress]
+
+执行 [HWLAB #2614](https://github.com/pikasTech/HWLAB/issues/2614)：将 CaseRun/HarnessRL 后端改造为 Temporal durable workflow，拆分 API 与 worker，提供 CLI local/`--over-api` 双模式、前端独立热重载 native 测试服务，先完成 native smoke，再通过原 PaC/Tekton/GitOps/Argo 自动链回归，禁止第二 authority、v0.2/direct route、fake 生产回退或人工 CI/CD，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4_Task_Report.md)。
+
+### R4.1 [completed]
+
+P0 SPEC 与服务合同：更新 PJ2026-0103 HarnessRL、CLI、Web/API 规格，冻结 Temporal workflow/activity、registry/read model、API/worker、native test 和 CI/CD 数据流；来源 HWLAB #2614，依赖无，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.1_Task_Report.md)。
+
+### R4.2
+
+P1 Temporal 后端：实现 HarnessRL durable registry、deterministic CaseRun workflow、idempotent activities、API/worker 独立服务、cancel 与重启恢复；依赖 R4.1，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.2_Task_Report.md)。
+
+### R4.3
+
+P2 CLI 双模式：CaseRun CLI 默认 local adapter，增加 --over-api 与 base-url，复用 application service/DTO、typed error 和 submit-and-poll 合同；依赖 R4.2，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.3_Task_Report.md)。
+
+### R4.4
+
+P3 前端 native 敏捷服务：提供独立 Vite HMR 与可热重载 CaseRun native test API/fixture，覆盖 queued/running/completed/failed/blocked/canceled、events 和 aggregate；依赖 R4.1，可与 R4.2/R4.3 低耦合并行，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.4_Task_Report.md)。
+
+### R4.5
+
+P4 native smoke：启动本地 Temporal、HarnessRL API/worker 与前端测试服务，验证 software-smoke、cancel、worker/API restart recovery 和 CLI local/over-api 等价；依赖 R4.2-R4.4，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.5_Task_Report.md)。
+
+### R4.6
+
+P5 CI/CD 与原入口回归：补齐服务制品和 GitOps，仅以 v0.3 PR merge 触发 PaC/Tekton/GitOps/Argo，验证 selected public origin CaseRun software-smoke 且原 CI/CD 可用；依赖 R4.5，完成任务后将详细报告写入[任务报告](./details/hwlab-caserun/R4.6_Task_Report.md)。

project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md

@@ -22,7 +22,7 @@
 | 短名 | HarnessRL |
 | 层级 | L1 方向 |
 | 状态 | 已生效 |
-| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
+| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-07-17-p0-temporal-native-agile |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |
@@ -41,6 +41,7 @@ Web CaseRun 是 HarnessRL 面向用户的正式端到端能力：用户从 YAML
 
 - CaseRun case definition、stage model、postValidation、run-local workspace 和 case registry 语义。
 - Web CaseRun 端到端语义，包括同源提交、短返回 runId、run stage 查询、AgentRun trace 引用、HWPOD operation result 引用、artifact/aggregate 归属和 web-probe 等价验收边界。
+- CaseRun durable workflow、API/worker 分离、取消与重启恢复，以及 native 前后端独立开发和 smoke 合同。
 - HWPOD raw output、Agent trace、artifact、diff、final response 和硬件观测之间的验证事实关系。
 - CaseRun 对 HWPOD 服务返回观测事实的引用，包括 probeId、单位、采样、统计和与硬件动作的关联；ioProbe 是其中一种 HWPOD 观测输入。
 - aggregate、评价、baseline、replay、失败分类和可复验比较。
@@ -69,6 +70,10 @@ Web CaseRun 是 HarnessRL 面向用户的正式端到端能力：用户从 YAML
 | ioProbe | 由 HWPOD 服务管理的板外物理状态观测探针，输出带单位、采样和统计语义的数据。 |
 | replay | 基于同一 case 和验证事实关系复核执行结果的能力。 |
 | 训练反馈 | 从成功/失败路径中沉淀出的 prompt、skill、case、reward 或策略改进材料。 |
+| CaseRun workflow | 由 Temporal 持久化推进的 CaseRun 编排历史，只拥有 stage 调度、retry、timer、signal、cancel 和恢复语义。 |
+| HarnessRL API | 提供 CaseRun admission、query、events、aggregate 和 cancel 的无状态 API 进程，不执行硬件 activity。 |
+| HarnessRL worker | 执行 CaseRun workflow 与 activity 的独立进程，不承载用户 HTTP API。 |
+| native 模式 | 不依赖 Kubernetes 即可独立启动 Temporal 开发运行时、API、worker、CLI adapter 和前端测试服务的开发形态；它不构成生产 fallback。 |
 
 ## 4. 系统边界和接口
 
@@ -102,10 +107,14 @@ flowchart LR
     P[web-probe 同源浏览器验收]
     C[HWLAB CLI thin client]
   end
-  subgraph API[HWLAB Cloud API]
+  subgraph API[HarnessRL API]
     R[CaseRun REST API]
-    H[HarnessRL CaseRun service]
-    A[Artifact / aggregate read model]
+    T[Temporal client]
+    A[Registry / aggregate read model]
+  end
+  subgraph Worker[HarnessRL Worker]
+    WF[Temporal CaseRun workflow]
+    AC[prepare / build / collect activities]
   end
   subgraph Agent[Agent编排]
     AR[AgentRun run / command / trace]
@@ -119,30 +128,33 @@ flowchart LR
   W --> R
   P --> R
   C --> R
-  R --> H
-  H --> AR
+  R --> T
+  T --> WF
+  WF --> AC
+  AC --> AR
   AR --> WS
-  H --> S
+  AC --> S
   S --> N
   N --> HW
   HW --> N
   N --> S
-  S --> H
-  AR --> H
-  H --> A
+  S --> AC
+  AR --> AC
+  AC --> A
   A --> R
 ```
 
-目标架构要求 Cloud Web、web-probe 和 CLI 都通过 YAML 选中的同一 Web origin 和同源 CaseRun API 访问同一 run 事实。默认 origin 是 public URL；当 node/lane YAML 显式选择 internal IP origin 时，本次端到端验收可以走内部 IP，但仍必须由 YAML 声明、由受控 CLI 解析并在证据中输出 selectedMode/sourcePath。HarnessRL 拥有 CaseRun stage、artifact manifest、aggregate、评价和 replay 语义；Agent编排拥有 AgentRun 执行生命周期；硬件池拥有 HWPOD 资源、租约、路由、HWPOD node 和原始硬件事实；客户端只展示和调用这些事实。
+目标架构要求 Cloud Web、web-probe 和 CLI `--over-api` 都通过 YAML 选中的同一 Web origin 和同源 CaseRun API 访问同一 run 事实。HarnessRL API 与 worker 必须是独立进程和独立部署对象。Temporal workflow history 只作为 durable orchestration authority；HarnessRL registry 是 run、stage event、workflow identity、artifact manifest 和 aggregate 的产品 read model 与归档索引；Agent编排和硬件池的事实权威保持不变。API 或 worker 重启不得使 workflow 退回进程内 memory state，也不得从 Temporal UI、stdout 或客户端投影合成业务成功事实。
 
 ### 5.2 目标数据流图
 
 ```mermaid
 flowchart TD
   Submit[用户或 web-probe 提交 caseId + hwpodId] --> Admission[CaseRun admission]
-  Admission --> Run[runId / stage=queued]
-  Admission --> Lease[HWPOD lease request]
-  Admission --> AgentRun[AgentRun run/command]
+  Admission --> Registry[registry runId / stage=queued]
+  Admission --> Workflow[Temporal workflow start]
+  Workflow --> Lease[HWPOD lease request]
+  Workflow --> AgentRun[AgentRun run/command]
   AgentRun --> Diff[subject worktree diff / final response]
   Lease --> Ops[HWPOD operation results]
   Ops --> Build[build/download/UART/raw facts]
@@ -150,12 +162,13 @@ flowchart TD
   Build --> Manifest
   AgentRun --> Manifest
   Manifest --> Aggregate[aggregate / evaluation / replay refs]
-  Aggregate --> Status[CaseRun status/read model]
+  Aggregate --> Registry
+  Registry --> Status[CaseRun status/read model]
   Status --> Web[Cloud Web run card]
   Status --> Probe[web-probe report]
 ```
 
-数据流必须保证：CaseRun admission 只短返回 runId 和查询入口；AgentRun trace、HWPOD operation result、diff、build/download/UART 证据和 aggregate 都以 artifact manifest 关联到同一 run；Web 和 web-probe 只读取同一 status/read model，不直接拼接 AgentRun、HWPOD 或本地文件事实。
+数据流必须保证：CaseRun admission 只短返回 runId、workflow identity 和查询入口；workflow activity 必须幂等，并以稳定 activity identity 写入 registry；AgentRun trace、HWPOD operation result、diff、build/download/UART 证据和 aggregate 都以 artifact manifest 关联到同一 run。Web、CLI `--over-api` 和 web-probe 只读取同一 status/read model。CLI local 模式复用同一 application service、DTO 和 workflow/activity 合同，但使用显式 local adapter，不把本地 fixture 写入生产 registry。
 
 ### 5.3 关键时序图
 
@@ -163,29 +176,36 @@ flowchart TD
 sequenceDiagram
   participant U as Web / web-probe
   participant API as CaseRun API
-  participant HR as HarnessRL
+  participant HR as HarnessRL API / Registry
+  participant TW as Temporal Workflow
+  participant WK as HarnessRL Worker
   participant AR as AgentRun
   participant HP as HWPOD service
   participant PN as Python UI node
   participant HW as STM32 / Arm2D HWPOD
   U->>API: POST /v1/caserun/runs
-  API->>HR: validate case + create run
+  API->>HR: validate case + create registry run
   HR-->>U: 202 runId + statusUrl
-  HR->>AR: create AgentRun run/command
-  HR->>HP: acquire lease + route operation
+  HR->>TW: start workflow
+  TW->>WK: schedule idempotent activities
+  WK->>AR: create AgentRun run/command
+  WK->>HP: acquire lease + route operation
   HP->>PN: dispatch debug/workspace/UART op
   PN->>HW: build/download/reset/UART
   HW-->>PN: raw hardware facts
   PN-->>HP: operation result
-  AR-->>HR: trace/result/diff refs
-  HP-->>HR: operation result refs
-  HR->>HR: write manifest + aggregate + stage terminal
+  AR-->>WK: trace/result/diff refs
+  HP-->>WK: operation result refs
+  WK->>HR: write stage / manifest / aggregate refs
+  WK-->>TW: activity result
   U->>API: GET status/events/aggregate
   API-->>U: run stage + trace + HWPOD evidence + aggregate
 ```
 
 关键时序要求长任务异步推进。`POST /v1/caserun/runs` 不等待 Agent、Keil、download 或 UART 完成；Web 和 web-probe 通过 status、events 和 aggregate 观察 terminal。HWPOD 写操作必须经 HWPOD 服务租约和 node 路由，不允许 Web、web-probe、CLI 或 Agent 直接连接用户 PC gateway、旧 v0.2 direct-url 或手工 SSH 路径。
 
+取消必须进入 Temporal signal/cancel 语义，并由 workflow 在 registry 中写入 durable `canceled` 终态。API 进程重启不得影响 workflow；worker 重启后必须从 Temporal history 恢复并继续未完成 activity。activity retry 不得复制 AgentRun command、HWPOD operation 或 artifact；已有下游 identity 必须通过稳定幂等键恢复。
+
 ## 6. 原子需求
 
 ### 6.1 HARNESS-L1-REQ-001 CaseRun 执行语义
@@ -200,6 +220,10 @@ CaseRun 语义必须引用 Agent 执行上下文和硬件事实，但不接管
 
 CaseRun stage model 至少应能表达 queued、preparing、agent-running、building、downloading、uart-reading、aggregating、completed、failed、canceled 和 blocked 等用户可理解状态。每个 stage 必须能关联其上游事实来源，例如 AgentRun run/command/trace、HWPOD operation result、artifact manifest 或 aggregate revision。
 
+CaseRun 必须由 Temporal durable workflow 推进。workflow 代码只包含确定性编排，所有文件系统、网络、AgentRun、HWPOD、registry 和时间相关副作用必须进入 activity。HarnessRL API 与 worker 必须分离；API 只承担 admission、query、events、aggregate 和 cancel，worker 只承担 workflow/activity。运行中的 workflow 不得依赖 API 进程内 `Map`、后台 Promise 或 Pod 本地 record 才能恢复。
+
+HarnessRL registry 必须使用 HWLAB 既有 PostgreSQL 运行面中的服务自有 schema/table 保存 run、stage event、workflow identity 和 artifact ref。Temporal history 与 registry 职责必须单向明确：Temporal 是编排历史权威，registry 是产品 read model 和归档索引；两者都不得覆盖 AgentRun 或 HWPOD 的领域事实。
+
 ### 6.2 HARNESS-L1-REQ-002 CaseRun 观测引用
 
 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -245,3 +269,7 @@ Web CaseRun 必须采用同源短返回 API：提交请求返回 runId 和状态
 Web CaseRun 的执行事实必须按职责分仓。AgentRun run、command、trace、diff 和 final response 归 Agent编排生产；HWPOD spec、租约、节点路由、operation result、Keil build、download、UART 和原始硬件事实归硬件池生产；HarnessRL 只把这些事实纳入 CaseRun stage、artifact manifest、aggregate、评价和 replay。任何模块缺失、延迟或失败时，CaseRun 应输出结构化 blocker 和事实来源，而不是用客户端文案、人工 steer、stdout 尾部或旧 CLI 成功样本补造成通过。
 
 Web CaseRun 的最小完成标准应先覆盖 compile-only case：同一 run 能从 Web 或 web-probe 提交，终态包含 caseId、runId、hwpodId、nodeId、AgentRun traceId、HWPOD operation result 引用、artifact manifest hash 和 aggregate。download+UART 与 Arm2D 场景可作为增强阶段，但其证据仍必须进入同一 CaseRun manifest 和 aggregate 语义。
+
+CaseRun 必须提供 repo-native 敏捷开发形态。后端应能在 Kubernetes 外独立启动 Temporal 开发运行时、HarnessRL API 和 worker，并分别支持 watch/reload；CLI 应提供默认 local 模式和显式 `--over-api` 模式，两者共享 application service、DTO、typed error 和 submit-and-poll 合同；前端应能独立启动 Vite HMR 与可热重载的 native CaseRun test API，覆盖 queued、running、completed、failed、blocked、canceled、events 和 aggregate。native fixture 必须显式标记 `mode=native-test`，不得成为生产 fallback 或通过判定来源。
+
+交付顺序必须先完成 native smoke，再回归原 CI/CD。native smoke 至少验证 software-smoke、cancel、API restart、worker restart recovery 和 CLI local/`--over-api` 合同等价；生产回归只由 `v0.3` PR merge 触发既有 GitHub webhook、Gitea snapshot、PaC、Tekton、GitOps/Argo 自动链，不得人工补跑或同步。

project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md

@@ -19,7 +19,7 @@
 | 短名 | Web工作台 |
 | 层级 | L2 课题 |
 | 状态 | 已生效 |
-| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; PJ2026-010401080313 Workbench实时权威 draft-2026-07-14-p0-pure-kafka-authority |
+| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-07-17-p0-caserun-native-hmr; PJ2026-010401080313 Workbench实时权威 draft-2026-07-14-p0-pure-kafka-authority |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |
@@ -509,6 +509,10 @@ CaseRun 入口应保持工作态密度。HWPOD 资源卡应展示资源身份、
 
 Web 工作台只调用 YAML-selected origin 下的同源 CaseRun API 和既有 Trace/aggregate/HWPOD 读侧入口。它不得直接访问 HWPOD node、本地 gateway、旧 v0.2 runner、数据库、Kubernetes、SSH 或未在 YAML 声明的临时内部服务来提交或判断 CaseRun。若 API 返回 HWPOD workspace missing、node offline、capability mismatch、probe mismatch、serial-monitor unavailable、AgentRun blocker 或 aggregate missing，Web 必须展示对应结构化 blocker 和可复制诊断，而不是改写为通用请求失败。
 
+CaseRun 前端必须支持独立 native 开发。Vite HMR 与 repo-owned native CaseRun test API 应能分别启动和热重载，前端不依赖 live Kubernetes、AgentRun、HWPOD 或生产数据库即可验证 queued、running、completed、failed、blocked、canceled、events 和 aggregate 展示。native test API 必须使用与生产 HarnessRL API 相同的 DTO 和相对 path，并显式返回 `mode=native-test`；它不得进入生产配置、selected origin 或线上 fallback。
+
+前端 native fixture 只提供确定的服务端状态序列。store、selector 和组件不得根据 elapsed time、HTTP 200、事件数量、按钮点击或 fixture 名称推断 terminal；Temporal workflow identity、stage、terminal、blocker 和 aggregate 仍只能来自 API read model。native 浏览器 smoke 通过不能替代 selected origin 的线上回归。
+
 线上 web-probe 对 CaseRun 的验收必须从同一 selected Web origin 进入。默认使用正式 public origin；本次 D601/v03 可以由 YAML 切换到 internal IP origin。web-probe 可以点击页面控件或调用页面同源正式 mutation，但不得绕过 Web session、不得使用未被 YAML 选中的内部 service URL、不得直接写 D601 文件系统、不得用 SSH 或手工 CLI 操作补齐硬件证据。web-probe 报告至少应记录 originMode、YAML source path、final URL、截图 SHA、caseId、runId、hwpodId、nodeId、traceId、HWPOD operation result 引用、aggregate 或 artifact manifest hash，以及是否存在用户可见 blocker。
 
 ### 6.13 CLIENT-WB-REQ-013 项目启动

project-management/PJ2026-01/specs/PJ2026-010402-hwlab-cli.md

@@ -19,6 +19,7 @@
 | 短名 | HWLAB CLI |
 | 层级 | L2 课题 |
 | 状态 | 已生效 |
+| 实现引用版本 | draft-2026-07-17-p0-caserun-local-over-api |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |
@@ -40,6 +41,7 @@ HWLAB CLI 负责提供 Cloud Web 的非视觉同源业务入口，使用户、
 - `client auth`、`request`、`rpc`、`access`、`provider-profiles`、`workbench`、`agent`、`gateway`、`harness` 等同源业务命令的命令形态、输出和错误语义。
 - 显式 Agent session 创建、选择、状态、send、result、trace、inspect、steer、cancel 和 composer policy 等非视觉入口。
 - CaseRun 和 HWPOD 相关组合入口的身份、trace/result 和下一步命令提示；具体 HWPOD 语义和 CaseRun 评价由对应模块负责。
+- CaseRun 默认 local 模式与显式 `--over-api` 模式的共享命令、DTO、错误和异步查询合同。
 - JSON 输出、默认摘要、`--full`/`--raw` 渐进披露、错误分类和敏感值不输出。
 
 ### 2.3 范围外
@@ -61,6 +63,8 @@ HWLAB CLI 负责提供 Cloud Web 的非视觉同源业务入口，使用户、
 | 显式 Agent session | 用户明确创建或选择的 Code Agent session，是普通 `send` 的前置条件。 |
 | Web renderer | Web trace 展示和 CLI `trace --render web` 共同使用的 trace row 转换语义。 |
 | 组合入口 | 上层 CLI 只返回 ID、摘要和下一步命令，完整业务语义继续交给已有 HWPOD、Agent 或 CaseRun 入口。 |
+| CaseRun local 模式 | 通过 HarnessRL application service 和 local adapter 使用 native Temporal/registry 的开发入口，不访问生产 API。 |
+| CaseRun `--over-api` 模式 | 通过选中 Web origin 的同源 `/v1/caserun/*` 调用 HarnessRL API 的入口。 |
 
 ## 4. 系统边界和接口
 
@@ -107,6 +111,10 @@ HWLAB CLI 应提供 Cloud Web 同源的 request、rpc、access、provider-profil
 
 同源请求不得把绝对 URL、内部 ClusterIP、Postgres、Kubernetes Service、Secret 或临时 fixture 当作正式用户入口。确需 Cloud API 直连的 gateway/HWPOD 诊断必须明确显示其诊断属性，不能替代 Web 用户流程通过结论。
 
+CaseRun 命令默认使用 local 模式；只有显式 `--over-api` 时才调用同源 HarnessRL API。两种模式必须复用同一 application service contract、request/response DTO、typed error、runId/workflow identity 和 submit-and-poll 命令形态。local 模式不得静默回退生产 API，`--over-api` 也不得在 API 失败后回退本地执行。
+
+CaseRun start 必须短返回 runId、workflow identity、mode 和下一步 status/events/aggregate 命令。status、events、aggregate 和 cancel 在两种模式下保持字段语义一致；测试 fixture 必须显式披露 `mode=native-test`，不能被 CLI 渲染为生产或硬件通过。
+
 ### 6.3 CLIENT-CLI-REQ-003 Agent 会话入口
 
 | 编号 | 短名 | 主责模块 | 关联模块 |