fix: make AgentRun CLI a render-only REST client (#263)

Co-authored-by: Codex <codex@noreply.local>

.agents/skills/unidesk-code-queue/SKILL.md

@@ -5,7 +5,7 @@ description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy
 
 # UniDesk Code Queue / AgentRun CLI
 
-旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障、残留任务停止和 prompt-lint 入口；新的指挥官派单、Aipod/Artificer 执行、events/logs/result、ack/cancel、dispatch、steer/send 必须走 AgentRun 资源原语，并按 cli-spec 渐进披露。默认输出是低噪声 human 表格/摘要；脚本读取显式使用 `-o json|yaml`，原始官方 bridge 调试显式使用 `--raw`。
+旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障、残留任务停止和 prompt-lint 入口；新的指挥官派单、Aipod/Artificer 执行、events/logs/result、ack/cancel、dispatch、steer/send 必须走 AgentRun 资源原语，并按 cli-spec 渐进披露。UniDesk 是 render-only client：默认输出是低噪声 human 表格/摘要，脚本读取显式使用 `-o json|yaml` 的稳定客户端 schema，`--raw` 只用于查看直连 AgentRun REST envelope。
 
 **固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts agentrun ...`
 
@@ -31,7 +31,7 @@ bun scripts/cli.ts agentrun get aipodspecs
 bun scripts/cli.ts agentrun describe aipodspec/Artificer
 bun scripts/cli.ts agentrun aipod-specs render Artificer --prompt-stdin
 
-# 旧 bridge 管理入口仍用于 AipodSpec apply/delete
+# AipodSpec apply/delete 仍由客户端资源原语发起，服务端只返回 REST 业务事实
 bun scripts/cli.ts agentrun aipod-specs apply --yaml-stdin --dry-run
 
 # 提交 AgentRun task manifest
@@ -59,7 +59,7 @@ bun scripts/cli.ts agentrun steer session/<sessionId> --prompt-stdin
 bun scripts/cli.ts agentrun cancel session/<sessionId> --reason <text> --dry-run
 ```
 
-日常 task manifest 优先使用 YAML heredoc：`agentrun apply -f -`；单 prompt 派单优先 `agentrun create task --aipod Artificer --prompt-stdin`。UniDesk bridge 会把 stdin 直通 G14 `/root/agentrun-v01` 官方 `./scripts/agentrun --manager-url auto` CLI，不先落 dump 文件；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只作为旧 bridge 兼容入口用于已审阅且可复用的受控文件。它不是旧 Code Queue adapter，不双写，也不迁移旧历史。
+日常 task manifest 优先使用 YAML heredoc：`agentrun apply -f -`；单 prompt 派单优先 `agentrun create task --aipod Artificer --prompt-stdin`。UniDesk 客户端按 `config/agentrun.yaml` 直连 AgentRun REST API，不经过 HWLAB runtime、SSH official CLI 或旧 bridge wrapper；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源，用于已审阅且可复用的受控文件。它不是旧 Code Queue adapter，不双写，也不迁移旧历史。
 
 `AipodSpec` 是 AgentRun v0.1 的声明式 agent 装配：模型 profile、gitbundle、skills/tools、SecretRef 和 tool credential 都从 YAML 规格渲染。`Artificer` 默认用于 UniDesk 分布式开发任务，使用 `sub2api` provider、`gpt-5.5`、`reasoningEffort=xhigh`，并通过 SecretRef 注入 GitHub PR token、GitHub SSH 和 UniDesk SSH 透传能力。更新规格时使用 `agentrun aipod-specs apply --yaml-stdin --dry-run` 先看计划，确认后再去掉 `--dry-run`；不得把 API key、SSH key 或 token 写入 prompt、payload、YAML 或 issue。
 
@@ -77,7 +77,7 @@ AgentRun queue 生命周期不是一个单独的 `queue lifecycle` 命令，而
 6. Session trace/output 只在 `describe task` 或 result 里有实际 `sessionId` 时使用 `logs|ack|steer|send|cancel session/<sessionId>`；`sessionRef=null` 时不要猜 session 命令。
 7. 已创建但尚未运行的 task 使用 `dispatch task/<taskId>` 派发，不再退回旧 bridge `queue dispatch`。
 
-默认视图必须低噪声且不是 JSON envelope，`-o json|yaml` 才输出稳定机器结构，`--raw` 才保留官方 AgentRun bridge 原始响应；命令返回里的下一步应优先是 `bun scripts/cli.ts agentrun ...` 资源原语，不得把人工 k8s 查询作为日常下一步。
+默认视图必须低噪声且不是 JSON envelope，`-o json|yaml` 才输出稳定机器结构，`--raw` 才保留直连 AgentRun REST envelope；命令返回里的下一步应优先是 `bun scripts/cli.ts agentrun ...` 资源原语，不得把人工 k8s 查询作为日常下一步。
 
 ## HWLAB Code Agent 入口整合
 

AGENTS.md

@@ -163,9 +163,9 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - UniDesk 同时存在 main server、D601 `~/cq-deploy` 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。
 - 任何开发、文档或部署配置变更开始前，必须先在当前 worktree 执行 `git status` 并从主线拉取最新源码：`git pull --ff-only origin master`；若本地并行变更或远端推进导致不能快进，必须当即分清来源并解决冲突后再继续。
 - 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 `git-spec` 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。
-- 提交前必须用 `git status` 和 `git diff` 确认工作区状态；遇到非本次任务的未推送提交一律可以直接推，遇到未提交修改一律可以一起提交并直接推；所有 UniDesk agent 变更只允许在 `master` 上开发并 `git push origin master`，禁止新建、切换到或推送其他分支；长期规则见 `docs/reference/arch.md`。
-- P0: 单纯文档或 UniDesk CLI/trans/tran/helper 变更默认直接提交并推送到 `origin master`，不开 PR、不建临时分支；若涉及外部仓库、发布线、运行面部署或服务高风险行为，按对应 reference 的显式规则执行。
-- `release/v1` 是规划中的稳定维护线，不是普通 feature/fix 分支；创建、更新或启用必须作为显式 release operation，先满足 `docs/reference/release-governance.md` 和 GitHub issue #6 的 CLI/CI/CD/文档条件。当前常规 agent 任务仍按 master-only 规则执行。
+- 提交前必须用 `git status` 和 `git diff` 确认工作区状态；UniDesk 默认集成线是 `master`，但 agent 开发必须优先在从最新 `origin/master` 创建的独立 `.worktree/<task>` 和任务分支中完成，避免污染固定主 repo；长期规则见 `docs/reference/arch.md`。
+- P0: 单纯文档或 UniDesk CLI/trans/tran/helper 变更属于轻量交付，默认仍以 `master` 为合入目标；可按任务风险直接合入/push，也可走短生命周期 PR，禁止在固定主 repo 根目录直接当 scratch 区修改。
+- `release/v1` 是规划中的稳定维护线，不是普通 feature/fix 分支；创建、更新或启用必须作为显式 release operation，先满足 `docs/reference/release-governance.md` 和 GitHub issue #6 的 CLI/CI/CD/文档条件。当前常规 agent 任务默认以 `master` 为集成目标，但不再禁止任务分支或 PR。
 - `frontend`、`scripts/cli.ts`、`trans`/`tran` 和分布式 SSH 透传能力跟随 `master`；`release/v1` 仅用于明确批准的 backend-core / Code Queue 稳定维护，不作为 frontend 或 CLI/trans/tran 修复的 backport 目标。
 
 ## Critical Master Server Build Ban

config/agentrun.yaml

@@ -0,0 +1,30 @@
+manager:
+  baseUrl: https://agentrun.74-48-78-17.nip.io/
+  timeoutMs: 15000
+
+publicExposure:
+  enabled: true
+  proxyName: agentrun-v01-frpc
+  remotePort: 22880
+  publicBaseUrl: https://agentrun.74-48-78-17.nip.io/
+  masterBaseUrl: http://127.0.0.1:22880
+  masterFrps:
+    configPath: /opt/hwlab-frp/frps.dev.toml
+    containerName: hwlab-frps-dev
+  masterCaddy:
+    enabled: true
+    domain: agentrun.74-48-78-17.nip.io
+    configPath: /etc/caddy/Caddyfile
+    serviceName: caddy
+    upstreamBaseUrl: http://127.0.0.1:22880
+    responseHeaderTimeoutSeconds: 60
+
+auth:
+  env: HWLAB_API_KEY
+  file: /root/.config/hwlab-v02/master-server-admin-api-key.env
+  header: Authorization
+  scheme: Bearer
+
+client:
+  role: render-only
+  transport: direct-http

docs/reference/agentrun.md

@@ -111,9 +111,11 @@ UniDesk 不能作为以下内容的事实来源：
 
 AgentRun `v0.1` 的指挥官任务面已经按 AgentRun issue #105 完成真实运行面验收，可作为新任务派发、commander queue 观察、events/logs/result、steer/send、ack 和 cancel 的 AgentRun 侧标准路径。长期使用时仍以 AgentRun 仓库自身 SPEC 为能力事实来源；UniDesk 只记录该路径已经通过 G14 `agentrun-v01` 运行面和 `hy` profile + `gpt-5.5` 验证。
 
-UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语。该入口是 G14 `/root/agentrun-v01` 中官方 `./scripts/agentrun --manager-url auto` CLI 的低噪声包装；默认 human 输出只显示表格、生命周期摘要和下一步命令，脚本读取显式使用 `-o json|yaml`，官方 bridge 原始响应显式使用 `--raw`。日常派单优先用 `agentrun create task --aipod Artificer --prompt-stdin` 或 `agentrun apply -f -` 的 quoted YAML/JSON heredoc/stdin 形式；已创建未运行任务用 `agentrun dispatch task/<taskId>` 派发；旧 bridge 的 `--json-file`、`--prompt-file` 和 `--runner-json-file` 只用于已审阅且可复用的兼容调试。UniDesk 不实现 AgentRun queue 协议，也不把任务 double-write 回旧 Code Queue。
+UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语。该入口是 render-only client：UniDesk 客户端保留 k8s 风格命令解析、human 表格、生命周期摘要、下一步命令、分页、`-o json|yaml` 稳定客户端 schema 和错误展示；AgentRun 服务端只提供稳定 RESTful API、鉴权和业务事实，不承载 UniDesk CLI 渲染。日常派单优先用 `agentrun create task --aipod Artificer --prompt-stdin` 或 `agentrun apply -f -` 的 quoted YAML/JSON heredoc/stdin 形式；已创建未运行任务用 `agentrun dispatch task/<taskId>` 派发；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源，用于已审阅且可复用的受控文件。UniDesk 不实现 AgentRun queue 协议，也不把任务 double-write 回旧 Code Queue。
 
-`agentrun control-plane ...`、资源原语和兼容 bridge 组共用同一 UniDesk SSH capture bridge。主 server 本机可继续使用本地 backend-core broker；AgentRun runner、Artificer 或其他没有本地 Docker / `unidesk-backend-core` 容器的环境会自动改走既有 frontend `/ws/ssh` WebSocket backend，并在输出的 `bridge.capture.backend`、`reason` 和 `localBackendCore` 中披露选择依据。本地 `unidesk-backend-core` 容器不是 runner 环境使用这些 AgentRun CLI 入口的隐式前置条件。若所有 capture backend 都不可用，CLI 必须返回 `failureKind=bridge-execution-environment` 与 `capture-backend-unavailable` 或 `bridge-execution-environment-unavailable`，并给出受控恢复入口；AgentRun 官方 CLI 自身返回的 run/command/schema 错误不得被改写成 bridge 失败。
+资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
+
+AgentRun 公网 HTTPS 入口按 Sub2API 的 FRP+Caddy 模式维护：`agentrun-v01` runtime 仍保持 ClusterIP，AgentRun source branch 的 `deploy/deploy.json` 声明 G14 frpc，把 `agentrun-mgr.agentrun-v01.svc.cluster.local:8080` 暴露到 master `127.0.0.1:22880`；UniDesk `config/agentrun.yaml` 声明 `https://agentrun.74-48-78-17.nip.io/`、master frps allow port、master Caddy vhost 和 direct REST 鉴权。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责补 master `frps` allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
 
 AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `unidesk-ssh`，长期契约以 AgentRun 仓库 `docs/reference/spec-v01-runtime-assembly.md` 和 `docs/reference/spec-v01-secret-distribution.md` 为准：调用方通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `UNIDESK_SSH_CLIENT_TOKEN` SecretRef；非敏感 endpoint 由 runner-job `transientEnv` 显式提供，或由 manager 受控默认值自动补齐。UniDesk bridge 提交 Queue payload 时不得在 prompt、payload 或 `transientEnv` 中携带 token，也不得使用 HWLAB runtime Web 入口冒充 UniDesk frontend。若 dispatcher 已正确请求 `unidesk-ssh` 但 trace 的 `runner-job-created.transientEnv.names` 没有 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`，归为 AgentRun assembly 问题；若 endpoint env 已存在但 route denied/timeout，再按 UniDesk frontend/token scope 或 provider session 排查。
 

docs/reference/arch.md

@@ -84,10 +84,10 @@
   - Multi-Repo Deployment Sync
     - The main server repository, D601 deployment tree, provider-local worktrees, and other live copies are working or deployment instances; the Git remote is the long-term project source of truth.
     - Before any development, documentation, or deployment manifest change, an agent must inspect the current worktree with `git status` and pull the latest source from the only accepted integration branch with `git pull --ff-only origin master`.
-    - If a pull, rebase, commit, or push is blocked by concurrent work, the conflict must be handled immediately in the current worktree by separating the current task's edits from unrelated parallel changes. Do not create a feature branch to postpone the conflict.
+    - If a pull, rebase, commit, or push is blocked by concurrent work, separate the current task's edits from unrelated parallel changes immediately. Use a task-scoped worktree/branch for isolation; do not use a hidden long-lived branch to postpone conflict resolution.
     - Any source, document, or persistent configuration change intended to survive the current task must be committed and pushed to the remote promptly after required self-tests or deployment validation, following `git-spec`.
-    - All UniDesk agent changes must be developed on `master` and pushed to `origin master`. Agents must not create, switch to, or push feature/fix branches for UniDesk work.
-    - Pure documentation changes and UniDesk CLI/trans/tran/helper changes use the same direct `master` path: commit the scoped change and push `origin master` without opening a PR or creating a temporary branch. External repositories, release-line work, runtime deployments, and high-risk service behavior follow their own explicit reference rules.
+    - `master` is the default UniDesk integration branch, but fixed root worktrees are anchors, not scratch space. Agent changes should be developed in task-scoped `.worktree/<task>` checkouts and may use short-lived task branches or PRs before merging to `master`.
+    - Pure documentation changes and UniDesk CLI/trans/tran/helper changes remain lightweight: target `master`, keep the diff scoped, and either merge/push directly after validation or use a short-lived PR when review/risk warrants it. External repositories, release-line work, runtime deployments, and high-risk service behavior follow their own explicit reference rules.
     - Live deployment should run from a known commit or from a change set that is immediately committed and pushed; local-only hotfixes must not become the implicit dependency for later tasks.
     - Secrets, tokens, generated runtime state, and node-local env files stay outside Git, but their required contract, storage location, and recovery path must be documented so pushing source changes is not blocked by runtime-only data.
   - Release And CI/CD Governance

docs/reference/cli.md

@@ -93,8 +93,9 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动
 - `ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。
 - `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule list`、`schedule get`、`schedule runs --limit N` 和 `schedule runs <scheduleId> --limit N` 是只读观察入口；`schedule run`、`schedule retry-run`、`schedule delete` 和 `schedule upsert-pgdata-backup` 会触发运行或写入配置，生产恢复时必须有明确授权。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。当 backend-core 目标容器缺失或只观察到 verify-only 容器时，schedule/microservice 命令必须以非零退出并返回 `failureKind=target-stack-not-running`、`runnerDisposition=infra-blocked`、`readOnlyCommands` 和 `authorizationRequiredForRecovery`，不得把 Docker 的 `No such container` 当成成功的空历史。
 - `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。
-- `agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 是当前指挥官新任务和 AgentRun session 控制入口。UniDesk CLI 通过 G14 `/root/agentrun-v01` 中官方 `./scripts/agentrun --manager-url auto` 执行，默认 human 输出只显示表格、生命周期摘要和下一步命令；脚本读取显式使用 `-o json|yaml`，官方 bridge 原始响应显式使用 `--raw`。日常查看用 `get tasks --queue commander`、`describe task/<taskId>`、`events run/<runId>`、`logs session/<sessionId>`、`result run/<runId> --command <commandId>`；日常写入用 `create task --aipod Artificer --prompt-stdin`、`apply -f -`、`dispatch task/<taskId>`、`steer/send session/<sessionId>`、`ack/cancel task|session/<id>`。兼容 bridge 组 `queue|runs|commands|runner|sessions|aipod-specs` 只保留为 raw/debug 和尚未包装的低频能力入口。
-- `agentrun control-plane ...`、资源原语和兼容 bridge 组共用 UniDesk SSH capture bridge。主 server 本机可使用本地 backend-core broker；Artificer/AgentRun runner 等没有本地 Docker 或 `unidesk-backend-core` 容器的环境会自动使用 frontend `/ws/ssh` WebSocket backend，并在 `bridge.capture.backend`、`reason`、`localBackendCore` 中披露选择依据。本地 `unidesk-backend-core` 不是 runner 环境的隐式前置条件；若 capture backend 不可用，错误必须归类为 `failureKind=bridge-execution-environment` 并给出受控恢复入口。
+- `agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 是当前指挥官新任务和 AgentRun session 控制入口。UniDesk CLI 是 render-only client：客户端保留 k8s 风格命令解析、human 表格、生命周期摘要、下一步命令、分页、`-o json|yaml` 稳定客户端 schema 和错误展示；AgentRun 服务端只提供稳定 RESTful API、鉴权和业务事实，不承载 UniDesk CLI 渲染。日常查看用 `get tasks --queue commander`、`describe task/<taskId>`、`events run/<runId>`、`logs session/<sessionId>`、`result run/<runId> --command <commandId>`；日常写入用 `create task --aipod Artificer --prompt-stdin`、`apply -f -`、`dispatch task/<taskId>`、`steer/send session/<sessionId>`、`ack/cancel task|session/<id>`。兼容 group `queue|runs|commands|runner|sessions|aipod-specs` 也走同一 direct HTTP transport，`--raw` 只披露直连 AgentRun REST envelope。
+- `agentrun` 资源原语的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
+- `agentrun control-plane expose --dry-run|--confirm` 按 `config/agentrun.yaml` 维护 AgentRun 公网 HTTPS 入口，模式与 Sub2API 暴露一致：G14 AgentRun runtime 通过 frpc 出到 master `127.0.0.1:<remotePort>`，master Caddy 提供 `https://agentrun.74-48-78-17.nip.io/`。该命令只补 master `frps` allow port 和 Caddy vhost；G14 frpc Deployment/ConfigMap 必须由 AgentRun `deploy/deploy.json` + GitOps render 管理，不能在 UniDesk 侧手写 Kubernetes manifest。
 - `codex submit/enqueue`、`codex steer`、`codex resume`、`codex queue create`、`codex queue merge`、`codex move`、旧 Web 提交表单、旧队列管理和旧 workdir 管理是冻结的 legacy Code Queue 写入口。CLI 必须返回 `ok=false`、`frozen=true`、`degradedReason=legacy-code-queue-frozen` 和 AgentRun 替代命令；服务端旧 API 写入口必须返回 410。新任务、steer/send、events/logs/result、ack 和 cancel 走 AgentRun 资源原语。
 - 旧 Code Queue 只保留历史归档、只读排障和残留任务停止。`codex task/tasks/output/read/unread/queues` 继续通过 backend-core 私有代理读取旧 PostgreSQL 历史；`codex interrupt|cancel <taskId>` 只用于停止旧运行面残留任务。旧 `steer-confirm` 只作为历史 trace confirmation 查询，不是新任务控制入口。
 - `codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N] [--full|--raw]` 通过稳定 `code-queue` proxy 请求 D601 scheduler `/api/runtime-preflight`，用于 PR 型派单 admission。默认输出是紧凑 commander 视图，显式分出 `schedulerPreflight` 与 `activeRunnerPrCapability`，并附带 `commands` 和 `disclosure`，方便先看 scheduler auth 缺口、再看当前 runner/dev container 的 `gh auth status` 与 `gh pr create --dry-run` 能力；`--full` 或 `--raw` 才展开完整 `preflight`、工具、agent port、Git worktree、GitHub egress、repo/issue/PR 只读探测和观测原文。只报告 `GH_TOKEN`/`GITHUB_TOKEN` 是否存在和来源 key，不打印值。当 auth-broker 配置存在时，`tokenCoverage.source="auth-broker"`、`credentialSource="broker-issued-token"` 且 runner env token 不是成功前提；当仅 env token 存在时，`credentialSource="env-token"` 且 `authBroker.nextAction="use-env-token-until-auth-broker-live"`；两者都缺失时顶层 `ok=false`、`runnerDisposition=infra-blocked`、`degradedReason=auth-broker-needed`，`tokenCoverage.missing` 同时列出 `GH_TOKEN` 与 `GITHUB_TOKEN`，并输出 `authBroker.source="broker/auth-broker-needed"`、`capability.source="missing-token"`。该 `auth-missing` 的 scope 是 `scheduler-runner-env`，不能简化成“当前 active runner/dev container 不能创建 PR”；默认视图必须带 `scopeBoundary` 和 `activeRunnerPrCapability`。GitHub DNS/API 连接失败应归类为 `failureKind=github-transient`、`degradedReason=github-dns-api-transient`，并带 `retryable=true`、`commanderAction=retry-backoff-or-keep-running-if-heartbeat-fresh` 和有界 `githubTransient.failedProbes`；调用方应重试/退避，且在任务 heartbeat/trace 新鲜时继续监督，不把它当成 auth 缺失或 PR 语义失败。`prCapability` 是 runner-facing 合同摘要，必须包含目标分支、token/auth 来源、`systemGhBinaryRequiredForWrites=false`、UniDesk REST `bun scripts/cli.ts gh` 可用性、push dry-run/PR create dry-run 的 `writesRemote=false`、expected PR handoff、真实 PR 创建需要 commander 授权，以及 guarded `gh pr merge --dry-run` 预检路径；系统 `gh` binary 缺失只进入 `tools.systemGhBinary`，不得误判为 UniDesk REST `gh` CLI 不可用。`--remote` 在 runner-like 环境里不再依赖本地 `unidesk-backend-core`、`unidesk-database`、`baidu-netdisk-backend` 容器存在；这些缺失只作为本地观测证据。若远程控制面可达，则继续走远程控制面结果；若远程控制面不可达，则结构化返回 `failureKind=control-plane-missing` / `degradedReason=remote-control-plane-unreachable`，而不是把本地 `backend-core-container-missing` 当作最终阻塞。`--pr-create-dry-run` 不 POST GitHub，只证明 runner 内 PR body 生成、`scripts/cli.ts gh pr create --dry-run` 和 branch 参数形态可用；服务端创建权限仍以 token/auth broker、repo/issue/PR read、push dry-run 和最终授权后的真实 PR 创建结果为准。

docs/reference/code-queue-supervision.md

@@ -93,7 +93,7 @@ HWLAB M3 口径使用同一分级：只读报告、fixture、LOCAL/DRY-RUN 和 d
 
 AgentRun 新派单和历史 Code Queue 审阅都按成本、可信度和 blast radius 分层：GPT-5.5/Codex 处理高风险和复杂任务，DeepSeek/OpenCode 处理中等复杂度且边界清晰的任务，MiniMax/OpenCode 处理简单、低权限、可复核任务，生产重启、密钥、数据库手工写入和运行中任务控制保留给指挥官或人工。
 
-当前新任务派发合同由 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语暴露：`get tasks --queue commander` 查看指挥官队列，`create task --aipod Artificer --prompt-stdin` 或 `apply -f -` 创建任务，`dispatch task/<taskId>` 派发，`events/logs/result/ack/cancel/steer/send` 读取和控制 AgentRun task、run 与 session。日常一次性 YAML/JSON 和 prompt 输入优先用 quoted heredoc/stdin；`--json-file`、`--prompt-file` 和旧 bridge 参数只用于已审阅且可复用的兼容调试。本地 UniDesk bridge 会把 stdin 直通官方 G14 `/root/agentrun-v01` CLI，不先落 dump 文件；它不是旧 Code Queue adapter，不做双写，也不迁移旧历史。
+当前新任务派发合同由 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语暴露：`get tasks --queue commander` 查看指挥官队列，`create task --aipod Artificer --prompt-stdin` 或 `apply -f -` 创建任务，`dispatch task/<taskId>` 派发，`events/logs/result/ack/cancel/steer/send` 读取和控制 AgentRun task、run 与 session。UniDesk 是 render-only client：日常一次性 YAML/JSON 和 prompt 输入优先用 quoted heredoc/stdin，客户端按 `config/agentrun.yaml` 直连 AgentRun REST API 并保留 k8s 风格渲染；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源。该路径不经过 HWLAB runtime、SSH official CLI 或旧 bridge wrapper，不做旧 Code Queue 双写，也不迁移旧历史。
 旧 `codex submit/enqueue`、`codex steer`、`codex resume`、旧 queue mutation、task move 和旧 workdir mutation 已冻结。CLI 必须返回 `ok=false`、`frozen=true`、`degradedReason=legacy-code-queue-frozen` 和 AgentRun 替代命令；服务端旧 API 写入口必须返回 410。旧 `codex task/tasks/output/read/unread/queues` 继续作为历史归档和只读排障入口，`codex interrupt|cancel` 只用于停止残留旧任务。
 
 新任务模型由 AgentRun task payload 和 AgentRun runtime 配置决定；旧 Code Queue 的 `CODE_QUEUE_MODELS` 只作为历史任务审阅和残留运行面配置参考，长期合同至少包含 GPT-5.5、GPT-5.4、GPT-5.4 Mini、DeepSeek Chat、MiniMax M3 和 MiniMax M2.7 两路并行配置；`deepseek`/`deepseek-chat`、`minimax-m3` 与 `minimax-m2.7` 会走 OpenCode port，其余模型走 Codex port。PROD 集群把 `MINIMAX_MODEL` 切到 `MiniMax-M3`（M3 是新任务的默认 provider model），judge 与 opencode 跟随；M2.7 仍然作为并行配置存在，切换只需把 `MINIMAX_MODEL` 改成 `MiniMax-M2.7` 后 rollout restart。两者不存在自动 fallback 关系：M3 任务失败不会自动改派 M2.7，task 要用 M2.7 必须显式 `--model minimax-m2.7`。只有当执行面 `/health` 或等价配置已经显示 DeepSeek 模型可用、并完成轻量 runner smoke 后，才允许真实提交 `--model deepseek-chat`。
@@ -189,7 +189,7 @@ CLI 是短 shout 的需求原语，不是长驻服务器进程。CLI 功能不
 
 所有 GitHub Markdown 正文写入优先使用 `--body-stdin` 或 `--body-file <file|->`。不要使用 `gh issue comment --body`、`gh api -f body=...` 或把多行正文直接拼进 shell 参数；这些路径容易把真实换行、反引号和 Markdown 表格污染成字面量 `\n` 或 shell escape。从 shell 生成正文文件时使用 quoted heredoc，例如 `cat <<'EOF' > /tmp/body.md`，保证反引号和反斜杠不被展开；JSON 请求体场景优先使用对应 CLI 的 `--body-file` 或 `--body-stdin`，不要把长 JSON 塞进命令行参数。`gh issue comment create|update|edit` 和 `gh pr comment create|update|edit` 都支持 `--body-stdin` 作为多行 Markdown 的第一等入口，`--body` 仅适合短单行文本。`gh issue` 正文更新主入口仍是 `update --mode replace|append --body-stdin|--body-file`，`edit` 只是兼容别名；`append` 会先读取当前正文再追加文件字节，保留真实换行、反引号和 Markdown 表格，不走 shell 拼接。`gh issue update --body-file` 默认拒绝 `null`、空白和过短正文；#20 自动要求 `## 看板（OPEN）`，指挥简报 profile 自动要求 `## 常驻观察与长期建议`，并允许 #24 legacy 或每日滚动简报 issue。更新 body-only issue 前优先跑 `--dry-run`，查看旧/新正文长度、body SHA、关键标题、字面量 `\n` 和 shell 污染信号；正式写入长期正文时优先带上 `--expect-updated-at` 或 `--expect-body-sha`，避免旧缓存覆盖新正文。指挥简报更新正文时默认只写 GitHub issue，不自动向 ClaudeQQ 推送；#24 legacy 可用 `--notify-claudeqq-brief-diff` 通知 helper，如确需提醒用户，按本文的 ClaudeQQ 通知门槛单独发送。提交前或巡检时可用 `gh issue scan-escape --limit N --dry-run` 或 `gh issue cleanup-plan --limit N` 只读扫描污染并生成建议，不自动修复。
 
-PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。默认 master-only 交付仍按项目 Git 规则执行；当变更风险高、跨模块、需要人工审查、或任务目标明确要求 PR 交付时，worker 可以创建 PR。PR 型任务必须报告源分支、目标分支、PR URL、关联 issue、测试证据和未完成风险。禁止把 PR 当成隐藏分支仓库；PR 分支必须来自最新目标线，保持小而可审查，并在合并后确认目标分支远端 commit 可 fetch。
+PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。UniDesk 默认集成目标仍是 `master`，但不再禁止任务分支；当变更风险高、跨模块、需要人工审查、或任务目标明确要求 PR 交付时，worker 可以创建 PR。PR 型任务必须报告源分支、目标分支、PR URL、关联 issue、测试证据和未完成风险。禁止把 PR 当成隐藏分支仓库；PR 分支必须来自最新目标线，保持小而可审查，并在合并后确认目标分支远端 commit 可 fetch。
 
 PR handoff 的职责默认分开：runner 实现、测试、提交、push head branch 并创建 PR；指挥官监督并发、steer、审阅、确认 checks 和合并裁决。短期内 GPT-5.5 runner 如果收到明确 PR 收口授权，并且 PR 是普通 UniDesk source 变更、checks 满足任务要求、无冲突且不涉及 prod/runtime/release/security/database/破坏性回滚，可以自行用 repo-owned GitHub merge/close 路径完成收口并报告 SHA。高风险、边界不清、checks 失败或用户/指挥官保留 final action 的 PR 仍必须交回 commander 审查。host commander 也不把直接编辑业务代码当成常规 PR 替代路径。
 

docs/reference/codex-deploy.md

@@ -70,7 +70,7 @@ D601 原生 k3s 的人工诊断必须显式使用 host kubeconfig：`KUBECONFIG=
 
 ## Pull Request Delivery
 
-Code Queue worker 可以在任务明确要求审查型交付时创建 Pull Request。PR 交付不是默认出口；默认集成仍遵循项目当前 master-only 规则，直到具体任务或指挥官要求改为 PR。PR 型任务必须从最新目标线创建短生命周期分支，报告源分支、目标分支、PR URL、关联 issue、验证证据和未完成风险；分支命名应使用 `probe/`、`code-queue/` 或其他明确任务前缀，禁止把隐藏分支当成长期交付状态。
+Code Queue worker 可以在任务明确要求审查型交付时创建 Pull Request。PR 交付不是唯一出口；默认集成目标仍是 `master`，轻量改动可直接合入，风险较高或需要审查的改动使用短生命周期 PR。PR 型任务必须从最新目标线创建短生命周期分支，报告源分支、目标分支、PR URL、关联 issue、验证证据和未完成风险；分支命名应使用 `probe/`、`code-queue/` 或其他明确任务前缀，禁止把隐藏分支当成长期交付状态。
 
 Code Queue runtime 提供 `/api/runtime-preflight` 作为 PR 能力探测入口；CLI 稳定入口是 `bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N]`。默认请求只检查本地工具、凭证可见性、Git worktree、HOME、known_hosts、agent port 和 proxy DNS；`--remote` 会增加 GitHub 网络、issue API、SSH/HTTPS `git ls-remote`、GitHub SSH、`gh auth status`、`gh repo view`、`gh issue read/view` 和只读 `gh pr list` 探测；`--push-dry-run` 会额外执行 `git push --dry-run`，验证远端写权限但不创建分支；`--pr-create-dry-run` 会在 runner 内生成受控 PR body 并执行 `scripts/cli.ts gh pr create --dry-run`，只证明 PR body guard 和命令形态可用，不 POST GitHub。探测输出只报告 `GH_TOKEN`/`GITHUB_TOKEN` 是否存在，不得输出 token 内容，并通过 `prCapabilityContract` 明确 token source、target branch、expected PR handoff、dry-run 不写远端和 merge unsupported 边界。缺少 runner env token 时，`authBroker.source="broker/auth-broker-needed"` 是标准结构化证据；系统 `gh` binary 缺失必须与 UniDesk REST `bun scripts/cli.ts gh` 可用性分开报告。backend-core 的稳定 `code-queue` proxy 必须把 `/api/runtime-preflight` 路由到 D601 scheduler，而不是主 server `code-queue-mgr`，因为 token 和 PR runner 能力属于执行面环境。
 

docs/reference/dev-environment.md

@@ -25,7 +25,7 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
 
 若路径、分支或 remote 不符合预期，先修正 fixed workspace，再继续。`/home/ubuntu/cq-deploy`、Code Queue pod 内 `/root/unidesk`/`/app`、D601 上的 `/root/unidesk` 和 `/tmp/unidesk-*` 只作为部署副本、运行副本或临时实验面；运行面热修可以直接作用在 pod/容器，但必须随后把持久化修复提交到 Git remote，并在 fixed workspace 中复验。
 
-固定 workspace 只作为 source truth 预检、fetch、worktree 管理和最终同步入口。实际开发、文档修改、测试补丁和 PR 准备应在固定 repo 下的独立 worktree 中完成，例如 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>`；该 worktree 必须从最新 `origin/master` 创建，使用任务专属分支或按当前 master-only 规则完成提交，结束前用 `git status` 确认只包含本任务文件。不要把 `/home/ubuntu/workspace/unidesk-dev` 根目录当作并行任务 scratch 区，也不要复用其他任务遗留 worktree。
+固定 workspace 只作为 source truth 预检、fetch、worktree 管理和最终同步入口。实际开发、文档修改、测试补丁和 PR 准备应在固定 repo 下的独立 worktree 中完成，例如 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>`；该 worktree 必须从最新 `origin/master` 创建，使用任务专属分支或 detached worktree 隔离当前改动，结束前用 `git status` 确认只包含本任务文件。不要把 `/home/ubuntu/workspace/unidesk-dev` 根目录当作并行任务 scratch 区，也不要复用其他任务遗留 worktree。
 
 Master server 不作为 UniDesk 重型验证机。仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译和 Code Queue runner 实测必须放到 D601、CI runner 或其他获批执行面；master server 只做轻量源码编辑、Git 操作、状态观察和受控调度。唯一例外是 backend-core 主 server 上线：当用户或 issue 明确要求把当前 backend-core 修复上线到主 server 时，可以用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价限流执行 backend-core 专属编译，并必须用异步 job/status/health 证据回写 issue。
 
@@ -117,7 +117,7 @@ Use this sequence for backend-core Rust and frontend dev work:
 
 1. Preflight the fixed workspace, then develop in a task-scoped `.worktree/<task>` created from the latest `origin/master`; keep unrelated parallel changes separated with `git status`/`git diff`.
 2. Run local non-Rust checks on the master server, for example `bun scripts/cli.ts check --files --scripts-typecheck --compose --logs`.
-3. Commit and push the code to `origin master`; `deploy apply --env dev` cannot deploy unpushed local changes.
+3. Commit the code from the task worktree and merge/push it to `origin/master` through the chosen lightweight PR or direct integration path; `deploy apply --env dev` cannot deploy unpushed local changes.
 4. Update `deploy.json` `environments.dev.services` so `backend-core` and `frontend` point at the pushed commit, then commit and push that manifest update.
 5. Preflight backend-core publication: `bun scripts/cli.ts ci publish-backend-core --commit <full-sha> --dry-run`. The result must have no `blockedScopes`, `wouldBuildOnD601=true`, D601 `unidesk-ci` Tekton runner metadata, D601 registry target `127.0.0.1:5000/unidesk/backend-core`, required labels for service id/source repo/source commit/Dockerfile, and `recommendedAction` pointing to the real publish command.
 6. Publish the artifact first: `bun scripts/cli.ts ci publish-backend-core --commit <full-sha> --wait-ms 1200000` for backend-core, or `bun scripts/cli.ts ci publish-user-service --service <frontend|decision-center|mdtodo|claudeqq|code-queue> --commit <full-sha> --wait-ms 1200000` for user services.

docs/reference/release-governance.md

@@ -31,7 +31,7 @@ Frontend and CLI ownership are intentionally separate from this stable line. The
 
 `release/v1` must not carry new product features, large architecture changes, the default Rust backend-core switch, or speculative Code Agent sandbox behavior. Any exception requires an explicit issue and a deployment rollback plan.
 
-Until the release-line implementation is completed in CLI, CI, CD and documentation, the current repository rule still applies: UniDesk agent changes are developed on `master` and pushed to `origin master`. Creating or updating `release/v1` is an explicit release operation, not a replacement for arbitrary feature or fix branches.
+Until the release-line implementation is completed in CLI, CI, CD and documentation, `master` remains the normal UniDesk integration target for agent changes. Task-scoped worktrees, short-lived branches and PRs are allowed for isolation and review, but creating or updating `release/v1` is an explicit release operation, not a replacement for ordinary task branches.
 
 ## Stabilization Mode
 

scripts/src/agentrun.test.ts

@@ -1,5 +1,50 @@
+import { readFileSync, rmSync } from "node:fs";
 import { describe, expect, test } from "bun:test";
-import { stripAgentRunResourceWrapperArgs } from "./agentrun";
+import { parseAgentRunClientConfigYaml, resolveAgentRunAuth, runAgentRunCommand, stripAgentRunResourceWrapperArgs } from "./agentrun";
+
+const agentRunClientYaml = [
+  "manager:",
+  "  baseUrl: https://agentrun.127-0-0-1.nip.io/",
+  "  timeoutMs: 15000",
+  "publicExposure:",
+  "  enabled: true",
+  "  proxyName: agentrun-v01-frpc",
+  "  remotePort: 22880",
+  "  publicBaseUrl: https://agentrun.127-0-0-1.nip.io/",
+  "  masterBaseUrl: http://127.0.0.1:22880",
+  "  masterFrps:",
+  "    configPath: /opt/hwlab-frp/frps.dev.toml",
+  "    containerName: hwlab-frps-dev",
+  "  masterCaddy:",
+  "    enabled: true",
+  "    domain: agentrun.127-0-0-1.nip.io",
+  "    configPath: /etc/caddy/Caddyfile",
+  "    serviceName: caddy",
+  "    upstreamBaseUrl: http://127.0.0.1:22880",
+  "    responseHeaderTimeoutSeconds: 60",
+  "auth:",
+  "  env: HWLAB_API_KEY",
+  "  file: /tmp/hwlab-api-key.env",
+  "  header: Authorization",
+  "  scheme: Bearer",
+  "client:",
+  "  role: render-only",
+  "  transport: direct-http",
+].join("\n");
+
+const agentRunMinimalClientYaml = [
+  "manager:",
+  "  baseUrl: http://agentrun.example.local:8080",
+  "  timeoutMs: 15000",
+  "auth:",
+  "  env: HWLAB_API_KEY",
+  "  file: /tmp/hwlab-api-key.env",
+  "  header: Authorization",
+  "  scheme: Bearer",
+  "client:",
+  "  role: render-only",
+  "  transport: direct-http",
+].join("\n");
 
 describe("AgentRun resource bridge argv", () => {
   test("does not forward UniDesk output flags to create task prompt argv", () => {
@@ -38,3 +83,82 @@ describe("AgentRun resource bridge argv", () => {
     ]);
   });
 });
+
+describe("AgentRun render-only REST client config", () => {
+  test("parses explicit YAML config for direct REST render-only client", () => {
+    const config = parseAgentRunClientConfigYaml(agentRunClientYaml, "config/agentrun.yaml");
+    expect(config.manager.baseUrl).toBe("https://agentrun.127-0-0-1.nip.io/");
+    expect(config.publicExposure?.publicBaseUrl).toBe("https://agentrun.127-0-0-1.nip.io/");
+    expect(config.publicExposure?.masterCaddy.domain).toBe("agentrun.127-0-0-1.nip.io");
+    expect(config.auth.env).toBe("HWLAB_API_KEY");
+    expect(config.auth.header).toBe("Authorization");
+    expect(config.auth.scheme).toBe("Bearer");
+    expect(config.client.role).toBe("render-only");
+    expect(config.client.transport).toBe("direct-http");
+  });
+
+  test("uses env auth before configured file auth without exposing the key", () => {
+    const config = parseAgentRunClientConfigYaml(agentRunClientYaml, "config/agentrun.yaml");
+    const auth = resolveAgentRunAuth(config, { HWLAB_API_KEY: "secret-value" });
+    expect(auth.source).toBe("env");
+    expect(auth.value).toBe("secret-value");
+  });
+
+  test("requires explicit render-only direct-http client contract", () => {
+    expect(() => parseAgentRunClientConfigYaml(agentRunClientYaml.replace("  transport: direct-http", "  transport: ssh-bridge"), "config/agentrun.yaml")).toThrow("client.transport must be direct-http");
+    expect(() => parseAgentRunClientConfigYaml(agentRunClientYaml.replace("  role: render-only", "  role: proxy"), "config/agentrun.yaml")).toThrow("client.role must be render-only");
+  });
+});
+
+describe("AgentRun default transport contract", () => {
+  test("server-facing compatibility groups use REST dispatcher, not official SSH CLI wrapper", () => {
+    const source = readFileSync(new URL("./agentrun.ts", import.meta.url), "utf8");
+    const commandRouter = source.slice(source.indexOf("export async function runAgentRunCommand"), source.indexOf("function isAgentRunRestCompatGroup"));
+    expect(commandRouter).toContain("runAgentRunRestCompatCommand");
+    expect(commandRouter).not.toContain("runOfficialAgentRunCli");
+    expect(commandRouter).not.toContain("runPreparedOfficialAgentRunCli");
+  });
+
+  test("resource verbs can use direct REST without UniDesk SSH config", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        expect(request.headers.get("authorization")).toBe("Bearer secret-value");
+        expect(url.pathname).toBe("/api/v1/queue/tasks");
+        expect(url.searchParams.get("queue")).toBe("commander");
+        expect(url.searchParams.get("state")).toBe("running");
+        return Response.json({
+          ok: true,
+          data: {
+            items: [
+              { id: "qt_1", state: "queued", queue: "commander" },
+            ],
+          },
+        });
+      },
+    });
+    const previousConfig = process.env.AGENTRUN_CLIENT_CONFIG;
+    const previousKey = process.env.HWLAB_API_KEY;
+    process.env.HWLAB_API_KEY = "secret-value";
+    const tempConfigPath = `/tmp/unidesk-agentrun-test-${process.pid}-${Date.now()}.yaml`;
+    try {
+      process.env.AGENTRUN_CLIENT_CONFIG = tempConfigPath;
+      await Bun.write(process.env.AGENTRUN_CLIENT_CONFIG, agentRunMinimalClientYaml.replace("http://agentrun.example.local:8080", server.url.href.replace(/\/$/u, "")));
+      const result = await runAgentRunCommand(null, ["get", "tasks", "--queue", "commander", "-o", "json"]);
+      expect(result.ok).toBe(true);
+      expect("renderedText" in result).toBe(true);
+      if ("renderedText" in result) {
+        expect(result.renderedText).toContain("\"kind\": \"TaskList\"");
+        expect(result.renderedText).toContain("\"name\": \"qt_1\"");
+      }
+    } finally {
+      server.stop(true);
+      if (previousConfig === undefined) delete process.env.AGENTRUN_CLIENT_CONFIG;
+      else process.env.AGENTRUN_CLIENT_CONFIG = previousConfig;
+      if (previousKey === undefined) delete process.env.HWLAB_API_KEY;
+      else process.env.HWLAB_API_KEY = previousKey;
+      rmSync(tempConfigPath, { force: true });
+    }
+  });
+});