docs: record sub2api timeout closeout and agentrun cli updates

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

@@ -1,11 +1,11 @@
 ---
 name: unidesk-code-queue
-description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读/残留停止/prompt-lint；新任务提交、Aipod/Artificer 派单、steer、resume、queue mutation、session trace/output/read/cancel、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun queue|runs|commands|runner|sessions|aipod-specs`。用户提到 codex、Code Queue、submit、steer、resume、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。
+description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读/残留停止/prompt-lint；新任务提交、Aipod/Artificer 派单、steer/send、events/logs/result、ack/cancel、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun get|describe|events|logs|result|ack|cancel|create|apply|steer|send` 资源原语。用户提到 codex、Code Queue、submit、steer、resume、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。
 ---
 
 # UniDesk Code Queue / AgentRun CLI
 
-旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障、残留任务停止和 prompt-lint 入口；新的指挥官派单、Aipod/Artificer 执行、trace/output、read/cancel、steer/reuse 必须走 AgentRun Queue/Runs/Commands/Runner/Sessions/AipodSpec，并按 cli-spec 渐进披露。
+旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障、残留任务停止和 prompt-lint 入口；新的指挥官派单、Aipod/Artificer 执行、events/logs/result、ack/cancel、steer/send 必须走 AgentRun 资源原语，并按 cli-spec 渐进披露。默认输出是低噪声 human 表格/摘要；脚本读取显式使用 `-o json|yaml`，原始官方 bridge 调试显式使用 `--raw`。
 
 **固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts agentrun ...`
 
@@ -15,52 +15,50 @@ description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy
 
 ```bash
 # 查看 AgentRun 指挥官队列
-bun scripts/cli.ts agentrun queue commander --reader-id <id>
-bun scripts/cli.ts agentrun queue commander --reader-id <id> --full
+bun scripts/cli.ts agentrun get tasks --queue commander --limit 20
+bun scripts/cli.ts agentrun get tasks --queue commander -o wide
 
-# 按已有 CLI 组合查看一个 Aipod/Queue run 生命周期；不要新增 queue lifecycle 命令
-bun scripts/cli.ts agentrun queue show <taskId>
-bun scripts/cli.ts agentrun queue show <taskId> --full
-bun scripts/cli.ts agentrun runs show <runId>
-bun scripts/cli.ts agentrun runs result <runId> --command-id <commandId>
-bun scripts/cli.ts agentrun runs events <runId> --after-seq <lastSeq> --limit 100 --tail-summary
-bun scripts/cli.ts agentrun commands show <commandId> --run-id <runId>
-bun scripts/cli.ts agentrun commands result <commandId> --run-id <runId>
-bun scripts/cli.ts agentrun runner jobs --run-id <runId> --command-id <commandId>
-bun scripts/cli.ts agentrun runner job-status <runnerJobId> --run-id <runId>
+# 查看一个 task/run/command/runnerjob/session 生命周期
+bun scripts/cli.ts agentrun describe task/<taskId>
+bun scripts/cli.ts agentrun events run/<runId> --after-seq <lastSeq> --limit 100
+bun scripts/cli.ts agentrun logs session/<sessionId> --tail 100
+bun scripts/cli.ts agentrun result run/<runId> --command <commandId>
+bun scripts/cli.ts agentrun describe command/<commandId> --run <runId>
+bun scripts/cli.ts agentrun describe runnerjob/<runnerJobId> --run <runId>
 
 # 查看 / 渲染 AipodSpec（Artificer 是默认分布式开发 agent）
-bun scripts/cli.ts agentrun aipod-specs list
-bun scripts/cli.ts agentrun aipod-specs show Artificer
+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
 
-# 提交 AgentRun Queue payload
-bun scripts/cli.ts agentrun queue submit --json-stdin <<'JSON'
-{
-  "tenantId": "unidesk",
-  "projectId": "example",
-  "queue": "commander",
-  "title": "任务标题",
-  "payload": {
-    "prompt": "任务说明"
-  }
-}
-JSON
+# 旧 bridge 管理入口仍用于 AipodSpec apply/delete
+bun scripts/cli.ts agentrun aipod-specs apply --yaml-stdin --dry-run
+
+# 提交 AgentRun task manifest
+bun scripts/cli.ts agentrun apply -f - --dry-run <<'YAML'
+kind: Task
+spec:
+  tenantId: unidesk
+  projectId: example
+  queue: commander
+  title: 任务标题
+  payload:
+    prompt: 任务说明
+YAML
 
 # 用 AipodSpec 提交，优先用于新任务和 Artificer
-bun scripts/cli.ts agentrun queue submit --aipod Artificer \
+bun scripts/cli.ts agentrun create task --aipod Artificer \
   --prompt-stdin --idempotency-key <key>
 
 # 查看/控制 AgentRun session
-bun scripts/cli.ts agentrun sessions trace <sessionId>
-bun scripts/cli.ts agentrun sessions output <sessionId>
-bun scripts/cli.ts agentrun sessions read <sessionId>
-bun scripts/cli.ts agentrun sessions turn <sessionId> --aipod Artificer --prompt-stdin
-bun scripts/cli.ts agentrun sessions steer <sessionId> --prompt-stdin
-bun scripts/cli.ts agentrun sessions cancel <sessionId>
+bun scripts/cli.ts agentrun logs session/<sessionId> --tail 100
+bun scripts/cli.ts agentrun ack session/<sessionId>
+bun scripts/cli.ts agentrun send session/<sessionId> --aipod Artificer --prompt-stdin
+bun scripts/cli.ts agentrun steer session/<sessionId> --prompt-stdin
+bun scripts/cli.ts agentrun cancel session/<sessionId> --reason <text> --dry-run
 ```
 
-日常一次性 JSON、prompt 和 runner JSON 输入优先使用 quoted heredoc/stdin：`--json-stdin`、`--prompt-stdin`、`--runner-json-stdin` 或 `--*-file -`。UniDesk bridge 会把 stdin 直通 G14 `/root/agentrun-v01` 官方 `./scripts/agentrun --manager-url auto` CLI，不先落 dump 文件；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只用于已审阅且可复用的受控文件。它不是旧 Code Queue adapter，不双写，也不迁移旧历史。
+日常 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，不双写，也不迁移旧历史。
 
 `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。
 
@@ -68,20 +66,20 @@ AgentRun Queue payload 需要 runner 内使用 UniDesk SSH 透传时，只通过
 
 ## Queue 渐进披露
 
-AgentRun queue 生命周期不是一个单独的 `queue lifecycle` 命令，而是一组现有 CLI 的渐进披露组合：
+AgentRun queue 生命周期不是一个单独的 `queue lifecycle` 命令，而是一组资源原语的渐进披露组合：
 
-1. 默认总览用 `queue commander --reader-id <id>`，只看 active/unread/terminal 摘要和少量任务行。
-2. 单任务用 `queue show <taskId>`，读取 `latestAttempt.runId`、`commandId`、`runnerJobId`、`sessionId/sessionPath`、Aipod metadata 和 `pollCommands`。
-3. Run 级状态用 `runs show <runId>` 和 `runs result <runId> --command-id <commandId>`，判断 claimed、lease、stale、terminalClassification、failureKind、provider interruption、timeoutBudget 和 recoveryActions。
-4. Command 级状态用 `commands show <commandId> --run-id <runId>` 和 `commands result <commandId> --run-id <runId>`，确认 command state、ack、terminal status 和结果摘要。
-5. Runner job 只读状态用 `runner jobs --run-id <runId> --command-id <commandId>` 和 `runner job-status <runnerJobId> --run-id <runId>`，确认 env image reuse、jobName、namespace、phase、exitCode、retention 和 `valuesPrinted=false`。不要为了这些字段手动调用 `trans G14:k3s kubectl ...`。
-6. Session trace/output 只在 `queue show` 或 result 里有实际 `sessionId` 时使用 `sessions trace|output|read|steer|cancel`；`sessionRef=null` 时不要猜 session 命令。
+1. 默认总览用 `get tasks --queue commander --limit 20`，只看 task state、queue/lane、run/cmd/rjob/session ref、age 和 attention。
+2. 单任务用 `describe task/<taskId>`，读取 `latestAttempt.runId`、`commandId`、`runnerJobId`、`sessionId/sessionPath` 和少量 `Next:`。
+3. Run 级状态用 `events run/<runId>` 和 `result run/<runId> --command <commandId>`，判断 terminalClassification、failureKind、provider interruption、timeoutBudget 和 recoveryActions。
+4. Command 级状态用 `describe command/<commandId> --run <runId>` 和 `result command/<commandId> --run <runId>`，确认 command state、ack、terminal status 和结果摘要。
+5. Runner job 只读状态用 `describe runnerjob/<runnerJobId> --run <runId>`，确认 env image reuse、jobName、namespace、phase、exitCode、retention 和 `valuesPrinted=false`。不要为了这些字段手动调用 `trans G14:k3s kubectl ...`。
+6. Session trace/output 只在 `describe task` 或 result 里有实际 `sessionId` 时使用 `logs|ack|steer|send|cancel session/<sessionId>`；`sessionRef=null` 时不要猜 session 命令。
 
-默认视图必须低噪声，`--full` 展开结构化详情，`--raw` 才保留原始响应；命令返回里的 drill-down 应优先是 `bun scripts/cli.ts agentrun ...`，不得把人工 k8s 查询作为日常下一步。
+默认视图必须低噪声且不是 JSON envelope，`-o json|yaml` 才输出稳定机器结构，`--raw` 才保留官方 AgentRun bridge 原始响应；命令返回里的下一步应优先是 `bun scripts/cli.ts agentrun ...` 资源原语，不得把人工 k8s 查询作为日常下一步。
 
 ## HWLAB Code Agent 入口整合
 
-HWLAB Code Agent / CaseRun follow-up 的日常派单也归入 AgentRun Queue/Sessions：新任务用 `queue submit --aipod Artificer` 或包含 HWLAB gitbundle 的 `queue submit --json-stdin`；运行中纠偏用 `sessions steer` 或 `sessions turn --aipod Artificer`。需要验证 HWLAB Web/Cloud API 原入口时，仍按 `$hwlab-code-agent` 使用 G14 `/root/hwlab-v02` 的 `hwlab-cli client agent ...` 拉取同一 trace/result/inspect；不要回到旧 `codex submit/resume/steer`。
+HWLAB Code Agent / CaseRun follow-up 的日常派单也归入 AgentRun 资源原语：新任务用 `create task --aipod Artificer` 或包含 HWLAB gitbundle 的 `apply -f -`；运行中纠偏用 `steer session/<sessionId>` 或 `send session/<sessionId> --aipod Artificer`。需要验证 HWLAB Web/Cloud API 原入口时，仍按 `$hwlab-code-agent` 使用 G14 `/root/hwlab-v02` 的 `hwlab-cli client agent ...` 拉取同一 trace/result/inspect；不要回到旧 `codex submit/resume/steer`。
 
 ---
 
@@ -111,7 +109,7 @@ bun scripts/cli.ts codex move <taskId> --queue <queueId>
 bun scripts/cli.ts codex tasks --view commander [--limit N]
 ```
 
-返回旧 Code Queue 历史/残留任务的有界 action map：active runners 计数、少量 active item、queued/retry_wait 计数、terminal-unread 总数、关键风险计数、分类计数和 drill-down 命令。新任务队列状态用 `agentrun queue commander`。
+返回旧 Code Queue 历史/残留任务的有界 action map：active runners 计数、少量 active item、queued/retry_wait 计数、terminal-unread 总数、关键风险计数、分类计数和 drill-down 命令。新任务队列状态用 `agentrun get tasks --queue commander`。
 
 ### Supervisor（分区视图）
 
@@ -189,7 +187,7 @@ bun scripts/cli.ts codex interrupt <taskId>
 bun scripts/cli.ts codex cancel <taskId>
 ```
 
-仅用于停止旧 Code Queue 残留任务；新 AgentRun session 使用 `bun scripts/cli.ts agentrun sessions cancel <sessionId>`。
+仅用于停止旧 Code Queue 残留任务；新 AgentRun session 使用 `bun scripts/cli.ts agentrun cancel session/<sessionId>`。
 
 ---
 

.agents/skills/unidesk-sub2api/SKILL.md

@@ -113,7 +113,7 @@ bun scripts/cli.ts platform-infra sub2api codex-pool expose --confirm
 
 - 由 `publicExposure` YAML 控制。默认公共端是 `publicBaseUrl`，master 本地消费端是 `masterBaseUrl`。
 - `expose --confirm` 只为 YAML 指定的 `remotePort` 补 master `frps` allow port，并在 G14 创建/更新 `sub2api-frpc`。
-- master Caddy site 也由 `publicExposure.masterCaddy` 渲染；`responseHeaderTimeoutSeconds` 必须足够覆盖 Codex `/responses/compact` 长请求，避免 Caddy 先返回 504 而 Sub2API 后台实际稍后成功。
+- master Caddy site 也由 `publicExposure.masterCaddy` 渲染；`responseHeaderTimeoutSeconds` 必须足够覆盖 Codex `/responses/compact` 长请求，避免 Caddy 先返回 504 而 Sub2API 后台实际稍后成功。具体数值只改 `config/platform-infra/sub2api-codex-pool.yaml`，修改后跑 `codex-pool expose --confirm`，再核对 Caddyfile 中渲染出的 `response_header_timeout`。
 - 同一个 FRP TCP 入口同时暴露 OpenAI-compatible API 和 Sub2API 管理 UI `/login`。不要另开第二个管理端口，除非 YAML 明确声明新的暴露决策。
 - Sub2API Kubernetes Service 继续保持 ClusterIP。
 
@@ -152,7 +152,7 @@ bun scripts/cli.ts platform-infra sub2api codex-pool configure-local --confirm
 - pool key 401：跑 `codex-pool sync --confirm` 重建 Sub2API key 与 k3s Secret 绑定，再跑 `codex-pool validate`。
 - 运行中过去的验证探针残留：只用 `codex-pool cleanup-probes --confirm` 清理 `unidesk-probe-*` 临时资源；不要把真实 managed account 删除当作探针清理或可用性恢复。
 - FRP 不通：先看 `codex-pool expose --confirm` 输出的 `masterFrps`、`masterCaddy`、`sub2api-frpc` 和 public 401 probe；需要低层证据时只用 `trans G14:k3s` 做 bounded 查询。
-- `/responses/compact` 约 30 秒后返回 504 但 Sub2API 日志稍后记录 `codex.remote_compact.succeeded` 时，优先检查 master Caddy `response_header_timeout` 是否由 YAML `publicExposure.masterCaddy.responseHeaderTimeoutSeconds` 渲染，修正后跑 `codex-pool expose --confirm`；这类边缘代理超时不会触发 Sub2API 账号级临时下线。
+- `/responses/compact` 在接近 master Caddy `response_header_timeout` 的固定时长后返回 504，或 Sub2API 日志稍后记录 `codex.remote_compact.succeeded` 时，优先检查 master Caddy `response_header_timeout` 是否由 YAML `publicExposure.masterCaddy.responseHeaderTimeoutSeconds` 渲染，修正后跑 `codex-pool expose --confirm`；这类边缘代理超时不会触发 Sub2API 账号级临时下线。reload 前已经在途的 compact 请求仍可能按旧 timeout 结束，判断修复是否生效时只看 reload 之后新发起的请求。
 - default profile 递归：检查 YAML default entry 是否使用 `*.pre-sub2api` 备份文件；必要时恢复备份后重新 `configure-local --confirm`。
 - 上游需要 WebSocket v2：先做 direct Codex WSv2 probe；通过后才给该 profile 配 `openaiResponsesWebSocketsV2Mode: ctx_pool|passthrough` 并跑 `sync --confirm`；把它当 capability candidate，容量仍以 YAML 中的 `capacity` 或默认值为准。
 - Codex 启动 WebSocket 回退：用原入口 Codex smoke 复现，再用 bounded Sub2API 日志确认 account；对 WS handshake 4xx/5xx、`openai.websocket_account_select_failed` 或 close-before-`response.completed` 的账号关闭 YAML WSv2 能力后同步。若没有剩余 WSv2-capable account，把 `localCodex.supportsWebSockets` 和 `localCodex.responsesWebSocketsV2` 一起关掉，不把临时可用性推断写成调度配置。