docs: document code agent profile inheritance

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

@@ -1,6 +1,6 @@
 # AgentRun Code Agent Dispatch
 
-本文定义 HWLAB Code Agent 通过 AgentRun `v0.1` 手动调度 API 执行时的装配边界。它只描述稳定的 payload、SecretRef 和 credential 归属，不替代当前 G14 DEV `/v1/agent/chat` 的真实 completed 判定。
+本文定义 HWLAB Code Agent 通过 AgentRun `v0.1` 调度 API 执行时的装配边界，也是 nested/child Code Agent provider profile 继承语义的唯一权威出处。它只描述稳定的 payload、SecretRef、credential、session/profile 归属和验收判定；CLI/Web 的用户入口只交叉引用本文，不重复定义继承规则。
 
 ## 装配入口
 
@@ -15,9 +15,24 @@
 - 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。
 - AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令，不创建新的 HWLAB session，也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`，并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收；目标 turn 后续 terminal 状态按原 command/result 判定。
 - 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 是用户可见 provider profile authority。`client agent session create --provider-profile <profile>` 建立 session 的 `providerProfile`，Cloud API 在 dispatch 时映射为 AgentRun `backendProfile`；后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时继承该 session 的 `providerProfile`。workspace 只记录当前已选 session 和展示 seed，不能作为 child agent profile 继承来源，也不得用旧 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 的长期目标。
 
+## Provider Profile 与 Child Agent 继承
+
+Nested/child `hwlab-code-agent spawn` 的 provider profile 继承只走环境变量通道。有效来源和优先级固定为：
+
+1. 显式 `spawn --profile <profile>`。
+2. runner 环境变量 `HWLAB_CODE_AGENT_PROVIDER_PROFILE`。
+
+未提供这两项时，`spawn` 必须 fail fast 返回 `provider_profile_required`。不得从 `skills/hwlab-code-agent/config.json`、账号 workspace、Cloud API 默认值、runner 默认 `deepseek`、历史 session、模型名或 profile 静态 allowlist 推断 child profile；也不得用 silent fallback 掩盖缺失配置。
+
+Parent -> child 传播链固定如下：外层 HWLAB request/session 解析出 `providerProfile` -> Cloud API/AgentRun adapter 解析当前 AgentRun `backendProfile` -> runner job `transientEnv` 注入 `HWLAB_CODE_AGENT_PROVIDER_PROFILE=<backendProfile>` 和 `HWLAB_CODE_AGENT_PARENT_TRACE_ID=<traceId>` -> runner 内的 `hwlab-code-agent spawn` 在没有显式 `--profile` 时读取该环境变量。`HWLAB_CODE_AGENT_PARENT_TRACE_ID` 只用于 trace/diagnostic 关联，不参与 profile 选择。
+
+可见性必须跟随同一链路：`spawn` JSON 输出暴露 `resolvedProviderProfile`、`profileSource` 和 `parentTraceId`；child trace/result 必须暴露真实 `providerProfile/backendProfile`、AgentRun infrastructure backend、provider 和 model。CaseRun `d601-f103-v2-leader-review` 使用 `dsflash-go` 时，Leader -> Coder/Reviewer child traces 应落到 `trc_dsflash-go_*`，child result backend 为 `agentrun-v01/dsflash-go`，model 为 `deepseek-v4-flash`，并由 compile check 与 reviewer verdict 形成业务通过证据。
+
+Provider profile slug 与配置是 AgentRun profile 管理数据，不是 Cloud API/Web 每次新增 slug 都要修改代码的枚举。HWLAB 已鉴权 CLI/Web/API 通过 [spec-v02-provider-management.md](spec-v02-provider-management.md) 委托 AgentRun 管理 profile config/credential/validate；只有共享运行面、bridge、SecretRef 约定或镜像变化才进入 GitOps/CI/CD。
+
 ## 架构混乱处理
 
 - 临时处理：排查 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 来掩盖缺口。
@@ -25,7 +40,7 @@
 
 ## Credential 边界
 
-- Provider credential 只通过 `executionPolicy.secretScope.providerCredentials[]` 的 AgentRun provider SecretRef 引用，默认随 `backendProfile` 选择 `agentrun-v01-provider-deepseek`、`agentrun-v01-provider-codex` 或 `agentrun-v01-provider-minimax-m3`。
+- Provider credential 只通过 `executionPolicy.secretScope.providerCredentials[]` 的 AgentRun provider SecretRef 引用。默认 SecretRef 随 `backendProfile` 解析为 `agentrun-v01-provider-<backendProfile>`；历史 alias 只允许表达已有 Secret 命名事实，例如 `codex-api -> codex`。动态 profile（如 `dsflash-go`）不得要求 HWLAB service 代码新增 allowlist 后才能 dispatch。
 - Provider API Key 的 Web 配置面归属 HWLAB `v0.2` 管理页，HWLAB Cloud API 通过已鉴权的管理接口委托 AgentRun 后端更新 profile Secret/配置；dispatch 路径只消费 AgentRun 返回的 SecretRef，不接收浏览器提交的 API Key 原文。完整管理规格见 [spec-v02-provider-management.md](spec-v02-provider-management.md)。
 - GitHub PR/issue 能力通过 `toolCredentials[].tool=github` 注入，默认 SecretRef 是 `agentrun-v01-tool-github-pr` key `GH_TOKEN`。
 - UniDesk SSH passthrough 通过 `toolCredentials[].tool=unidesk-ssh` 注入，默认 SecretRef 是 `agentrun-v01-tool-unidesk-ssh` key `UNIDESK_SSH_CLIENT_TOKEN`。
@@ -49,5 +64,5 @@
 - 源码合同测试：`node --test internal/agent/agentrun-dispatch.test.mjs`。
 - 语法检查：`node --check internal/agent/agentrun-dispatch.mjs && node --check internal/agent/agentrun-dispatch.test.mjs`。
 - 合同必须证明 `UNIDESK_SSH_CLIENT_TOKEN` 不出现在 `transientEnv`，GitHub/UniDesk SSH 能力都通过 AgentRun `toolCredentials` SecretRef 装配，且 runner resource bundle 默认暴露 `hwpod`、`unidesk-ssh`、`promptRefs` 和 `skillRefs`。
-- 真实 CLI 验收默认使用短 prompt 走 `backendProfile=deepseek`：首轮 prompt “不调用工具的情况下，你可见的 skill 有哪些？”应能回答 HWLAB bundle skill；同一会话 continuation 应显示 AgentRun 原生 resume 语义且不重复注入 initial prompt；“检查 HWPOD 状态”应触发 `hwpod inspect` 或等价 HWPOD node-ops 路径，若失败则报告正式 blocker，不切换 fallback。
-- 如果 DeepSeek profile 的 trace 明确失败为 AgentRun `provider-auth-failed`，且上游错误码或消息是 `INSUFFICIENT_BALANCE` / account balance 不足，则该次 CLI 验收改用 `--provider-profile minimax-m3` 继续执行同一短 prompt 组。这个规则只替换 provider profile，不替换 AgentRun 装配标准：仍必须使用同一个 `ResourceBundleRef`、`promptRefs`、`skillRefs`、`toolAliases`、Codex stdio `thread/start` / `thread/resume`，不得拼接历史上下文，不得切回旧 HWLAB prompt/skill 注入方式，也不得用 codex-api、generic shell、gateway shell 或诊断镜像作为替代验收。
+- 真实 CLI 验收必须使用目标 profile 显式创建 session，例如 `--provider-profile dsflash-go`，再发送至少一个不传 `--provider-profile` 的 turn，证明 send 继承 session profile；不得因为某个 provider 失败自动切换 profile 并把结果记为原 profile 通过。
+- Nested profile 继承验收必须覆盖 runner env：父 AgentRun result/trace 显示目标 `backendProfile`，child `spawn` 输出 `resolvedProviderProfile=<profile>`、`profileSource=env`、`parentTraceId=<outerTraceId>`，child trace/result 使用同一个 profile/model/backend。缺少任意字段时先修可见性，不新增旧 fallback、旧门禁或兼容分支。