fix: 收敛受控 CLI 调用与诊断

docs/reference/cli.md

@@ -22,7 +22,19 @@ UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式
 
 `trans` wrapper 是 SSH/WSL/k3s 透传的唯一默认入口：人工/Codex 远端操作、长期参考文档、AGENTS 索引、CLI help、非交互脚本和非交互 `exec` 都必须直接调主 server PATH 上的 `/root/.local/bin/trans`；禁止把 `bun scripts/cli.ts ssh ...`、`bun scripts/cli.ts trans ...` 或任何带 `bun scripts/cli.ts` 前缀的透传写法作为默认入口。`bun scripts/cli.ts help`、`config`、`server`、`provider`、`microservice` 等普通根 CLI 子命令不受这条限制，仍使用 `bun scripts/cli.ts <command>`，避免透传命令和根子命令在调用前缀上互相混淆。
 
-误写 `bun scripts/cli.ts trans ...` 或 `bun scripts/cli.ts tran ...` 时，根 CLI 必须返回结构化 `trans-root-cli-entrypoint-moved` 错误、`replacementExamples` 和 `Use: trans <route> <operation> [args...]` 迁移提示，不能退化成通用 `Unknown command`。
+误写 `bun scripts/cli.ts trans ...` 或 `bun scripts/cli.ts tran ...` 时，根 CLI 必须在本地返回紧凑的 `trans-root-cli-entrypoint-moved` 输入错误、精确 `usage` 替代命令和 `Use: trans <route> <operation> [args...]` 迁移提示，不能连接运行面、披露 stack 或退化成通用 `Unknown command`。
+
+- `trans` 的 cwd 与本地校验合同：
+  - host/workspace 的 cwd 只写入 route，例如 `trans NC01:/root/unidesk exec git status --short` 或 `trans NC01:/root/unidesk bash <<'BASH'`；
+  - k3s workload 的容器 cwd 使用 route 后缀或 `exec --cwd /absolute/path -- <command>`；
+  - host/workspace 上误用 `exec|argv|sh|bash --cwd` 时，必须在选择 transport 和连接运行面前返回 `trans-host-cwd-belongs-in-route` 与精确替代命令；
+  - `trans --help` 必须直接展示 host/workspace 与 k3s cwd 摘要，`trans --help exec|bash` 提供可执行示例。
+
+- Code Agent 跨服务只读诊断合同：
+  - `platform-infra observability diagnose-code-agent` 是 AgentRun durable authority、HWLAB projection/read model 与 OTel 服务覆盖的单命令聚合入口；
+  - 默认 text 与显式 `--full|--raw` JSON 必须共同披露 `typed outcome`、`effectiveStatus`、`mutation=false`、durable authority 和 projection 状态；
+  - AgentRun 权威终态与 HWLAB 投影不一致时，以权威终态作为有效结果，并将投影滞后或冲突标记为 `warning=true`、`blocking=false`；
+  - 聚合入口只读，不得触发 mirror sync、PipelineRun、Argo refresh/sync 或运行面修补。
 
 Windows `ps` 的参数语义分为两种：单个参数是完整 PowerShell source；多个参数是边界明确的 argv。后者对 native application 使用 Windows 命令行引用规则，必须保留 `python -c` 代码中的路径、`encoding="utf-8"`、字典 key 和嵌套引号，并继承 route 对应的 Windows workspace。PowerShell prelude 将 `Get-Content` 默认编码固定为 UTF-8；Windows fs helper 的 `head` / `tail` 同时支持 `-n N`、`-nN`、`--lines=N` 和 GNU `-N`，`wc -l` 必须把选项与路径分开解析。