feat: 源码化 Code Agent PC gateway 能力路由

docs/reference/code-agent-chat-readiness.md

@@ -66,6 +66,20 @@ report、issue、PR 或截图。
 - OpenAI Responses fallback 只能标记为 `openai-responses-fallback` /
   `text-chat-only`，不得满足 Codex runner capability gate。默认路径不得用 fallback
   冒充完整 Code Agent；仅明确允许 fallback 时才可作为普通文本备用通道返回。
+- 已登记 PC gateway `shell.exec` capability 是受控硬件能力例外：当请求能从显式
+  `projectId/gatewaySessionId/resourceId/capabilityId` 或唯一 DEV MVP topology 解析时，
+  `/v1/agent/chat` 可以选择 `hwlab-hardware-capability` runner，经 cloud-api 进程内
+  JSON-RPC helper 调用 `hardware.invoke.shell`。该 helper 必须使用冻结的
+  `hwlab-cloud-api` service id 常量，返回 payload 需包含 `toolCalls[]`、`operationId`、
+  `dispatchStatus`、`exitCode`、stdout/stderr 摘要、`runnerTrace.eventLabels` 与
+  `capabilityLevel`。拓扑缺失、不唯一、gateway offline、session/capability missing、
+  dispatch failed 或 JSON-RPC meta/serviceId 无效时必须返回结构化 blocker，不能转入
+  Codex stdio 或 OpenAI 文本 fallback 冒充成功。
+- `security.hardware-boundary` 仍然阻断直接 gateway/box-simu/patch-panel URL、`/invoke`、
+  `/sync/tick` 和泛化硬件写绕过；受控 `hardware.invoke.shell` capability route 只允许
+  已登记、可解析的 cloud-api 调用，不开放任意 shell。JSON-RPC/REST bridge 拒绝未知
+  `serviceId` 时，错误原因应可见为 `unknown serviceId ...` 或等价结构化 reason，且不得泄露
+  Secret/token。
 
 当前 DEV/runtime 若要升级为完整 #275 runner，至少需要 repo-owned 的 Codex CLI/stdio 或等价
 runner 二进制/协议适配、session supervisor 生命周期、workspace mount 与 sandbox 合同、token/Secret