fix: 支持 AgentRun render-only REST 入口 (#170)

Co-authored-by: AgentRun Codex <agentrun-codex@users.noreply.github.com>

docs/reference/spec-v01-agentrun-mgr.md

@@ -80,6 +80,12 @@ PATCH /api/v1/commands/:commandId/status
 
 所有 API 成功和失败响应都必须是 JSON。失败响应至少包含 `failureKind`、`message` 和 trace correlation；不得出现空 stdout/空 response 被误判为成功的情况。
 
+### API 鉴权边界
+
+`/health`、`/health/live` 和 `/health/readiness` 是公开健康探针，不要求鉴权。`/api/v1/**` 在 runtime 中必须要求 `Authorization: Bearer <token>`，server 侧只从 `AGENTRUN_API_KEY` 或 `AGENTRUN_API_KEY_FILE` 读取期望 token；缺少 server token 时启动为本地/自测宽松模式，但 runtime Deployment 必须通过 `managerApiKeyEnv` 注入 `AGENTRUN_API_KEY`。鉴权失败返回 JSON：缺 server token 且 runtime 要求鉴权时为 `failureKind=auth-missing` / HTTP 503，客户端未带或带错 token 时为 `failureKind=auth-failed` / HTTP 401。
+
+UniDesk 或其他客户端可以参考 HWLAB 的 key 发现风格，把本机 `HWLAB_API_KEY` 映射成 AgentRun REST bearer token，但这只是客户端凭据来源约定，不代表 AgentRun 依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 HWLAB 用户会话。AgentRun manager 只校验 bearer token 是否等于自身 `AGENTRUN_API_KEY`，不读取 HWLAB 的鉴权状态。
+
 ### v0.1.1 Session state 存储 API
 
 在 `P1 SessionRef 持久化` 升级到「per-session RWO PVC 直接挂载」后，manager 必须提供下列受控 API 来管理 session 的 PVC 生命周期：

docs/reference/spec-v01-cicd.md

@@ -37,7 +37,7 @@
 | Argo CD AppProject | `argocd/agentrun-v01` |
 | Argo CD Application | `argocd/agentrun-g14-v01` |
 
-公网入口暂不作为 `v0.1` 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。
+`v0.1` manager 允许按仓库声明的 FRP TCP 暴露给 UniDesk render-only client：`deploy/deploy.json` 的 `managerPublicExposure` 是 GitOps 渲染真相，当前把 `agentrun-mgr.agentrun-v01.svc.cluster.local:8080` 通过 `agentrun-v01-frpc` 暴露到 master `127.0.0.1:22880`，公共 URL 为 `https://agentrun.74-48-78-17.nip.io/`。master 侧 frps allow port 与 Caddy vhost 由 UniDesk `config/agentrun.yaml` 和 `bun scripts/cli.ts agentrun control-plane expose --confirm` 维护，模式对齐 Sub2API；本仓库只渲染 G14 runtime 内的 frpc Deployment/ConfigMap。不得临时固化 NodePort、host port、pod IP、一次性 port-forward，或增加 HWLAB 转发层。
 
 ## Bun + TypeScript CI 边界
 
@@ -117,7 +117,7 @@ Env identity 的输入至少包含：`imageRef.repoUrl`、`imageRef.commitId`、
 - replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。
 - runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。
 - Postgres 和 Code Agent provider 的 SecretRef 名称、key 名称与 mount/env intent；Secret 值不在 source 或 GitOps 中出现。
-- public/ingress intent 的声明占位；`v0.1` 默认不要求公网入口。
+- `managerPublicExposure` FRP intent，用于 UniDesk render-only client 直连 AgentRun REST；只允许声明 proxy name、FRP server、ClusterIP local target、remote port、public HTTPS URL 和 master local URL，不承载 master Caddy 配置。
 
 禁止写入 `deploy/deploy.json` 的内容：
 

docs/reference/spec-v01-cli.md

@@ -126,6 +126,8 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 
 - CLI 配置必须显式校验；部署关键值不得静默 fallback。
 - CLI 调用 manager REST API；不得直接连 Postgres 或读 Kubernetes Secret value。
+- CLI 可以直接连接公网 HTTPS manager，例如 `https://agentrun.74-48-78-17.nip.io/`，但它仍只是 REST client：CLI 渲染、k8s 风格命令、human 输出、分页、`--full|--raw` 渐进披露都保留在客户端；manager 只返回稳定 JSON 业务事实，不承载 UniDesk 或其他客户端的展示逻辑。
+- 调用 runtime `/api/v1/**` 时 CLI 必须发送 `Authorization: Bearer <token>`。客户端 token 可以来自 `AGENTRUN_API_KEY`、`HWLAB_API_KEY` 或对应 `*_FILE`，但输出只能展示来源、是否存在、hash/preview 等 redacted 元数据，不得打印 token value。`/health*` 探针不要求鉴权。
 - CLI 可以显示 SecretRef 名称、key、credential source、tool credential scope 和 readiness，但不得显示 Secret value、Codex `auth.json`、Codex `config.toml`、DSN password、token、SSH private key 或 URL credential。
 - CLI 不得把 GitHub token、UniDesk SSH client token、provider key 或长期 SSH key 通过 `transientEnv` 传入 runner；涉及 agent shell/tool 授权时，必须先按 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 的 `toolCredentials` 装配路径实现，再提供 CLI 参数。非敏感服务地址例如 `UNIDESK_MAIN_SERVER_IP` 可以作为 runner-job `transientEnv` 的执行上下文注入。
 - Debug 子命令可以用于开发，但综合联调和测试规格不得用 debug 子命令作为通过证据。