feat: add bounded cicd long polling

docs/MDTODO/cli-output-progressive-disclosure.md

@@ -143,6 +143,6 @@
 
 解决 [UniDesk #1656](https://github.com/pikasTech/unidesk/issues/1656)：由 Artificer 在独立 `.worktree/cicd-status-visibility`、`fix/cicd-status-visibility` 分支修复 `cicd status --node` 成功零输出，并统一 PaC consumer 的 registry applicability；GitOps-only/publisher-only 应显示 N/A 且由 PipelineRun、GitOps/Argo 与 runtime 证据闭环，只有 owning YAML 明确声明 image/registry 的 consumer 才把 registry missing 作为 blocker。保持默认输出有界、text/JSON/YAML 同构、缺失可选 YAML 事实降级为 warning，不新增严格合同或手工交付入口；补针对性测试和 `unidesk-cicd` 说明，提交独立 PR 且不自行合并，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R10_Task_Report.md)。
 
-## R11 [in_progress]
+## R11 [completed]
 
 解决 [UniDesk #2104](https://github.com/pikasTech/unidesk/issues/2104)：把 CLI-SPEC 的只读观测等待规则和 `unidesk-cicd` 受控观测入口统一为默认 `120s` 长轮询，目标完成或状态满足时立即返回，未完成等待至超时并明确返回当前状态、timedOut 与稳定继续入口；禁止 CLI 本地高频短轮询、忙轮询和无输出，mutation 与交付 authority 保持 fire-and-forget，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R11_Task_Report.md)。

docs/MDTODO/details/cli-output-progressive-disclosure/R11_Task_Report.md

@@ -0,0 +1,36 @@
+# R11 任务报告
+
+## 任务上下文
+
+- MDTODO：R11。
+- GitHub issue：`pikasTech/unidesk#2104`。
+- Target：NC01。
+- targetWorkspace：`/root/unidesk/.worktree/cicd-long-poll-observe`。
+- repository：`pikasTech/unidesk`。
+- ref：`feat/cicd-long-poll-observe`。
+
+## 完成内容
+
+- 新增仓库权威 `cli-spec` skill，明确只读观测默认 `120s` 长轮询、严格 duration、终态立即返回和 timeout 可见性。
+- 新增通用 `read-only-long-poll` 状态机，支持稳定 cursor、虚拟时钟、错误透传和取消语义。
+- 将 PaC `closeout --wait` 从 CLI 本地每 `3s` 重复全量 status 改为目标控制面 Kubernetes watch 驱动。
+- PipelineRun 与 PaC 共用同一 watch 判定：空成功为正常 timeout、`141` 为首事件后的 SIGPIPE，其他非零保留认证、网络或 API 错误。
+- 新增 `--timeout 120s`，timeout 输出当前状态、`timedOut`、`elapsed`、identity/cursor 和 `next.wait`。
+- capture 使用显式调用级 transport timeout，并保留用户 `60m` timeout 所需的固定余量，不依赖全局 env。
+- 更新 `unidesk-cicd`、CLI help 和 `docs/reference/cli.md`，明确禁止调用侧 `1s`、`5s` 高频轮询。
+- 权威 `cli-spec` 更新位于 `pikasTech/agent_skills#12`，UniDesk 仓内未保留重复 skill。
+- 未修改 AgentRun events 或 `unidesk-code-queue`，未改变 CI/CD、GitOps、Tekton 或 Argo authority。
+
+## 验证
+
+- `bun test scripts/src/read-only-long-poll.test.ts`。
+- `bun test scripts/src/kubernetes-watch.test.ts scripts/src/read-only-long-poll.test.ts scripts/src/ssh.test.ts`，共 38 项通过。
+- `bun test scripts/src/cicd-pr-merge-auto-delivery-doc-contract.test.ts scripts/src/cicd-node-status.test.ts`。
+- `bun scripts/cli.ts platform-infra pipelines-as-code help compatibility-diagnostics`。
+- 非法 `--timeout 1.5s` 被严格拒绝。
+
+## 证据边界
+
+- primary workspace 只用于读取 resource bundle skills 与执行 `trans` wrapper。
+- 源码读取、修改、测试和 Git 操作全部在 Target route `NC01:/root/unidesk/.worktree/cicd-long-poll-observe` 完成。
+- 本任务不部署、不触发 PipelineRun、不执行 Argo refresh，也不手工触发 CI/CD。

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 默认输出与帮助输出是直接阅读入口：