feat: add bounded cicd long polling

docs/reference/cli.md

@@ -1,5 +1,15 @@
 # UniDesk CLI Reference
 
+## 只读观测长轮询
+
+- mutation、构建、发布和部署触发保持 fire-and-forget；长轮询只属于只读观测，不改变执行 authority。
+- 只读等待默认 timeout 为 `120s`，显式覆盖只接受 `<正整数>ms|s|m`，最大 `60m`。
+- 后端 API、Kubernetes watch、事件流或原生通知负责持有等待；CLI 调用侧禁止 `1s`、`5s` 高频短轮询、忙轮询和重复全量扫描。
+- 成功、失败、取消或满足条件时立即返回；未完成时保持单次等待到 timeout。
+- timeout 和零变化必须返回当前状态、`timedOut=true`、`elapsed`、稳定 identity/cursor 与继续等待命令。
+- watch 断连和后端错误必须可见并保持原错误语义，不能伪装成 timeout、空变化或成功。
+- CI/CD 通用入口是 `bun scripts/cli.ts platform-infra pipelines-as-code closeout --target <NODE> --consumer <consumer> --wait --timeout 120s`。
+
 UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式固定为 `bun scripts/cli.ts <command>`；普通根 CLI 子命令仍使用该入口。`trans <route> ...` 是 SSH/WSL/k3s 透传专用入口，wrapper 委托轻量 `scripts/ssh-cli.ts` 启动链路，避免被无关根 CLI 子命令模块的解析或语法错误拖垮；长期参考文档、AGENTS 索引、CLI help 和人工远端操作示例都必须优先写 `trans ...`，不得再把 `bun scripts/cli.ts ssh ...` 作为默认透传入口。面向人工的默认输出采用 Kubernetes 风格的简洁表格、短摘要和 drill-down 命令；JSON 只用于 `--json`、`--raw`、`--full`、`-o json` 或其他明确机器消费模式。所有成功和失败路径仍必须给出可判定状态，避免无输出造成不可观测。
 
 - 高频 CLI 默认输出与帮助输出是直接阅读入口：