docs: record CLI closeout friction

docs/reference/cli.md

@@ -60,9 +60,9 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P
 - `gh auth status [--repo owner/name]` 探测 GitHub 操作前置条件并输出脱敏 JSON：是否存在 `gh` binary、是否存在 `GH_TOKEN`/`GITHUB_TOKEN` 或可用 `gh auth token` fallback、REST API 是否可达、目标 repo 是否可见、issue 是否可读。degraded reason 必须归类为 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response` 或 `unsupported-command`，不得打印 token；失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应优先用该字段分流。`github-transient` 表示 GitHub DNS/API 连接在收到 HTTP 状态前失败，输出应带 `retryable=true` 或等价 commander action；这不是缺 token、认证失败、权限不足或 PR 语义失败。
 - `codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` 是派发/steer 前的本地 dry-run prompt lint。它只读取 prompt 文本，返回 `dryRun=true`、`mutation=false`、`declaredClass`、`effectiveClass`、`requiredClass`、`dispatchDisposition`、缺失或矛盾项和有界 evidence，不访问 live service、不提交任务、不打印完整 prompt。分级固定为 `read-only`、`live-read`、`live-mutating`；未声明时按 `read-only` 处理。`codex submit --dry-run` 与 `codex steer --dry-run` 会嵌入同一 `promptLint` 结果，帮助指挥官在 dispatch/steer 前发现缺失或矛盾的 live mutation 授权。长期规则见 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级。
 - `gh issue list [owner/repo] [--state open|closed|all] [--limit N] [--search text] [--label label[,label...]]... [--repo owner/name] [--json number,title,state,url,updatedAt,createdAt,author,labels] [--raw|--full]` 通过 GitHub REST 列出 issue，默认 `state=open`、`limit=30`，输出稳定 JSON 且不依赖系统 `gh` binary。`owner/repo` 位置参数是 `--repo owner/repo` 的兼容别名；若位置 repo 与 `--repo` 冲突，或位置参数不是 `owner/repo`，必须结构化失败，禁止静默 fallback 到默认 repo。`--limit` 是 CLI 返回上限，不等同 GitHub 单页 `per_page`：当 `--limit > 100` 或默认页中混入 PR 时，CLI 必须分页抓取 GitHub REST/Search page，过滤 PR 后再返回 issue，并在输出中披露 `pagination.fetchedPages/rawCount/hasMore`；`hasMore=true` 时只能说明当前有界扫描未穷尽，禁止把它当作“仓库没有更多 issue”。`--search` 使用 GitHub Search Issues API，并自动追加 `repo:<owner>/<name>`、`type:issue` 和 state qualifier，用于创建新 issue 前做低摩擦查重；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`--label` 是 GitHub REST `labels=label1,label2` 或 Search `label:` 服务端过滤，支持重复 `--label` 和逗号分隔；filter 不在本命令上下文中使用（如 `issue read`、`pr list`）必须结构化失败并指明 `gh issue create/list/stale-close` 才是合法作用域。GitHub issues API 可能混入 PR，CLI 会从 `.data.issues` 中过滤 pull request。`--raw|--full` 在 `gh issue list` 上是绕过 20 KiB stdout 截断的显式开关：响应结果会带 `noDump=true`，`output.ts` 据此跳过 head/tail 替换并把完整数据 inline 输出；当响应未超阈值时 `--raw|--full` 行为等价默认。
-- `gh issue lifecycle`：`--state` 只能作为 `gh issue list` / `gh issue board-row list` / `gh pr list` 的过滤参数；`gh issue update` / `gh issue edit` 只写 body/title，**不接受** `--state` 改 open/closed。把 `gh issue update <n> --state closed` 落到错命令上时，CLI 必须返回 `validation-failed` 并显式提示 `gh issue close <n>` / `gh issue reopen <n>`（PR 用 `gh pr close|reopen <n>`），并把 5 条受支持命令放进 `supportedCommands`，禁止把"无 `--state` 改 issue 状态"的命令升级为"接受 `--state`"。`gh issue close|reopen` 成功输出默认是 compact issue 摘要，不得回显完整 `issue.body`；需要正文时后续使用返回的 `readCommands` 或 `gh issue read --json body|--full|--raw`。issue 硬删除走 `close`，PR 硬删除走 `close`，两者都没有"delete"语义。
+- `gh issue lifecycle`：`--state` 只能作为 `gh issue list` / `gh issue board-row list` / `gh pr list` 的过滤参数；`gh issue update` / `gh issue edit` 只写 body/title，**不接受** `--state` 改 open/closed。把 `gh issue update <n> --state closed` 落到错命令上时，CLI 必须返回 `validation-failed` 并显式提示 `gh issue close <n>` / `gh issue reopen <n>`（PR 用 `gh pr close|reopen <n>`），并把 5 条受支持命令放进 `supportedCommands`，禁止把"无 `--state` 改 issue 状态"的命令升级为"接受 `--state`"。`gh issue close|reopen` 成功输出默认是 compact issue 摘要，不得回显完整 `issue.body`；需要正文时后续使用返回的 `readCommands` 或 `gh issue read --json body|--full|--raw`。生命周期 close/reopen 的评论只接受短 `--comment`（或无评论），不接受 `--comment-file` 或 `--body-file`；需要附长篇 CLI 验收证据时，先用 `gh issue comment create <n> --body-file <file|->` 写证据评论，再用 `gh issue close <n> --comment <短引用>` 关闭。issue 硬删除走 `close`，PR 硬删除走 `close`，两者都没有"delete"语义。
 - `gh issue stale-close [--repo owner/name] [--inactive-hours N] [--limit N] [--label label[,label...]]... [--dry-run]` 是可复用批量生命周期清理入口，用于“超过 N 小时无回复或修改的 open issue 一律关闭”这类策略。判定基准固定为 GitHub `updatedAt < observedAt - inactiveHours`，issue comment、body/title 修改和 state 变化都会刷新 `updatedAt` 并视为活跃；PR 必须过滤，不参与 issue 关闭。默认 `inactive-hours=48`，默认扫描预算为 issue list 上限，输出必须包含 `observedAt`、`cutoffAt`、`scannedCount`、`staleCount`、`pagination.hasMore`、候选/关闭 issue 的 compact 摘要和失败列表，不得打印完整正文。正式关闭前建议先跑 `--dry-run`；真实执行后用同一命令加 `--dry-run` 验证 `staleCount=0`，且只有 `hasMore=false` 才能把当前扫描视为完整穷尽。HWLAB 当前长期策略使用 `bun scripts/cli.ts gh issue stale-close --repo pikasTech/HWLAB --inactive-hours 48 --dry-run` 观察，再移除 `--dry-run` 关闭。
-- `gh issue read <number|owner/repo#number> [--repo owner/name] [--json body,title,state,comments] [--raw|--full]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；`view` 只保留为兼容别名。`owner/repo#number` shorthand 会自动派生 `--repo owner/repo` 和 issue number；若同时提供冲突的显式 `--repo`，CLI 必须结构化失败并给出 `gh issue read <number> --repo owner/repo --json body,title,state,comments` 与 shorthand raw 的可执行命令。兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw` 与 `--full` 是显式完整披露别名：read/view 会选择完整支持字段集；issue update/edit 只有显式传入时才在成功响应里包含完整 `.data.issue.body`。当最终 `gh` JSON 超过 20 KiB 时，CLI 必须把完整 JSON 写入 `/tmp/unidesk-cli-output/*.json`，stdout 只返回 `outputTruncated=true`、dump path、总 bytes/lines 和 head/tail 预览。默认 list/read 输出仍不得扩散到无界非 JSON 文本。`gh issue create --title <title> --body-file <file|-> [--label label[,label...]]... [--dry-run]`、`gh issue update <number> --mode replace|append --body-file <file|-> [--title ...] [--dry-run] [--full|--raw]`、`gh issue comment create <number> (--body-file <file|->|--body <short-text>) [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--dry-run]`、`gh issue stale-close [--inactive-hours N] [--dry-run]` 都走 REST，不依赖 `gh` binary。`--body` 仅用于 issue comment 的短单行文本；空白、多行、疑似 shell 污染、secret-like 或过长 inline body 必须结构化失败，Markdown/生成内容/长评论继续用 `--body-file <file|->`。`--label` 用于 `issue create`、`issue list` 和 `issue stale-close`，支持重复传入和逗号分隔；`issue create --dry-run` 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 `validation-failed`，不静默成功。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。
+- `gh issue read <number|owner/repo#number> [--repo owner/name] [--json body,title,state,comments] [--raw|--full]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；`view` 只保留为兼容别名。`owner/repo#number` shorthand 会自动派生 `--repo owner/repo` 和 issue number；若同时提供冲突的显式 `--repo`，CLI 必须结构化失败并给出 `gh issue read <number> --repo owner/repo --json body,title,state,comments` 与 shorthand raw 的可执行命令。兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw` 与 `--full` 是显式完整披露别名：read/view 会选择完整支持字段集；issue update/edit 只有显式传入时才在成功响应里包含完整 `.data.issue.body`。当最终 `gh` JSON 超过 20 KiB 时，CLI 必须把完整 JSON 写入 `/tmp/unidesk-cli-output/*.json`，stdout 只返回 `outputTruncated=true`、dump path、总 bytes/lines 和 head/tail 预览。默认 list/read 输出仍不得扩散到无界非 JSON 文本。`gh issue create --title <title> --body-file <file|-> [--label label[,label...]]... [--dry-run]`、`gh issue update <number> --mode replace|append --body-file <file|-> [--title ...] [--dry-run] [--full|--raw]`、`gh issue comment create <number> (--body-file <file|->|--body <short-text>) [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--comment <short-text>] [--dry-run]`、`gh issue stale-close [--inactive-hours N] [--dry-run]` 都走 REST，不依赖 `gh` binary。`--body` 仅用于 issue comment 的短单行文本；空白、多行、疑似 shell 污染、secret-like 或过长 inline body 必须结构化失败，Markdown/生成内容/长评论继续用 `--body-file <file|->`。`--label` 用于 `issue create`、`issue list` 和 `issue stale-close`，支持重复传入和逗号分隔；`issue create --dry-run` 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 `validation-failed`，不静默成功。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。
 - `gh issue update <number> --mode replace|append --body-file <file|->` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件或 stdin 正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件或 stdin 字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和指挥简报类 issue 是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用 #20/#24 legacy guard：#20 必须包含 `## 看板（OPEN）`，#24 legacy 指挥简报必须包含 `## 常驻观察与长期建议`。显式 `--body-profile commander-brief` 不再固定 #24；#24 仍兼容，标题为 `YYYY-MM-DD 指挥简报（北京时间）` 或既有正文首行/关键 heading 表明为每日滚动指挥简报的 issue 也合法，并仍必须包含 `## 常驻观察与长期建议`。对非简报 issue 显式使用 `commander-brief` 会结构化失败为 `profile-issue-mismatch`。`--dry-run` 不 PATCH GitHub，输出有界 `bodyPreview`/`bodyPreviewLines`、新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格、shell 污染信号、`guard`、`concurrency`、`bodyOnlySafety` 和 `wouldPatch`；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入默认先读取当前 issue，执行 guard 和显式 `--expect-*` 并发校验，再 PATCH；成功输出 compact issue 摘要、old/new body SHA、updatedAt、bodySource 和 drill-down `readCommands`，不包含完整 `issue.body`。完整正文必须显式 `--full|--raw` 或后续执行 `readCommands.body/full/raw` 获取。
 - #20 只允许承担长期 UniDesk 指挥官 / Code Queue / CLI / infra 治理总看板职责；每日进展必须写入当天滚动指挥简报 issue，并由 #20 顶部“指挥简报索引”引用。HWLAB 用户反馈、Cloud Workbench、DEV-LIVE、M3 虚拟硬件可信闭环等产品 issue 必须写到 `pikasTech/HWLAB`；#20 只可记录 UniDesk 侧 commander/Code Queue/CLI/infra 支撑工作。`gh issue read/view 20` 会返回 `codeQueueBoardHint`；`gh issue update/edit 20` 的 body guard 会拒绝 `## 更新 YYYY-MM-DD HH:mm 北京时间`、`## YYYY-MM-DD HH:mm 北京时间指挥更新` 和 `### YYYY-MM-DD HH:mm CST：...` 这类简报段落；把 `pikasTech/HWLAB#N`、`HWLAB#N` 或 HWLAB 产品/live 验证行写入 #20 时只返回 warning 和 `codeQueueBoardHint`，不再拒绝正文 replace，以避免历史正文或治理交叉引用造成次生阻塞；`gh issue board-row list|get|update|add|move|delete|upsert --board-issue 20` 也会返回同一 hint，提醒不要把每日简报或 HWLAB 产品看板混入 #20。
 - `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是 legacy #24 指挥简报的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。每日滚动简报 issue 可用普通 `gh issue update <number> --body-profile commander-brief --dry-run` 和并发 guard 更新，但此通知 helper 仍只支持 #24。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`；`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL` 只接受 backend-core `/api/microservices/claudeqq/proxy` 等价路径，非 proxy URL 会结构化为 `notification-path-unavailable`。可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 调整开关、目标和超时。
@@ -194,6 +194,8 @@ CLI 会在 Host route、workspace route、k3s 控制面脚本和 pod route 的 s
 
 长任务的标准形态是：用一次短 `tran <route> script` 启动目标侧 job、后台进程、PipelineRun 或受控命令，并把 job id、日志路径、状态文件或 Kubernetes 对象名写到目标侧；后续用多次短 `tran` 查询 `status`、`logs --tail`、`kubectl get/describe`、trace result 或工具自带 job-status。不要为了观察 Docker build、镜像 push、Keil 下载、串口抓取或 Code Agent turn，把 `tran` 一直挂到结束；超过 60 秒的断开只说明调用方式需要改成轮询，不应立即归因成 provider session、CI/CD 或硬件失败。
 
+HWLAB `hwlab-cli client agent` 端到端验证经 UniDesk `tran`/`ssh` 进入 G14 时，也按短连接 submit-and-poll 执行：在目标 workspace 和锁定 runtime env 下先 `agent send` 提交 turn，避免在可能超过 60 秒的路径上使用 `--wait` 长挂；随后多次短查询 `agent result <traceId>`、`agent trace <traceId> --render web` 或 `agent inspect --trace-id <traceId>` 取证。关闭 context-loss、AgentRun 复用或多轮会话类 issue 时，证据至少应记录 `conversationId`、`sessionId`、`threadId`、`traceId`、`runId`、`commandId` 和关键 event label。需要验证“第二轮继承第一轮上下文”时，显式传入同一 conversation/session/thread 标识，不能依赖旧 Cloud Web workspace 历史或人工印象；`--no-workspace` 这类绕过恢复的实验只可作为定位证据，不能替代默认入口验收。
+
 `bun scripts/cli.ts ssh D518` 应表现为登录 D518 WSL 的 shell；`bun scripts/cli.ts ssh D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `bun scripts/cli.ts ssh D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `bun scripts/cli.ts ssh D601 script <<'SCRIPT'`。
 
 UniDesk CLI/tran 客户端改进本身是 master server 高频控制入口维护，可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；不要为这类客户端小改强制迁移到 D601 worktree。该例外不改变 master server 禁重型验证规则：仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译、Code Queue runner 实测仍必须在 D601、CI runner 或目标运行面执行。若 `tran`/SSH 文件传输遇到 provider-gateway 单次 stdin、argv 或 stdout 限制，先在 CLI 客户端做分块、SHA-256 校验、失败可观测输出和最小真实闭环；只有 client 侧不能解决且有证据时，才改 provider-gateway。`upload`/`download` 成功 JSON 中的 `verified=true`、`verification.automatic=true`、`verification.verified=true` 和 `verification.match.{bytes,sha256}=true` 就是端到端完整性证明，调用方不需要再额外手写 `sha256sum` 比对。

docs/reference/g14.md

@@ -84,6 +84,8 @@ For HWLAB user-feedback, CLI, Cloud Web, AgentRun, device-pod, public API, or ru
 
 The closing comment for these issues must include the actual command or entry path, target lane or endpoint, relevant trace/session/thread/PipelineRun/run/device ids, and the pass/fail result. If the original entry cannot be verified because rollout has not happened, credentials are unavailable, the target runtime is down, or the required CLI capability is missing, keep the issue open and record the blocker. Do not close the issue on the strength of PR merge, targeted tests, or "will be verified after rollout" wording. If an issue was closed before this real CLI/user-entry validation, reopen it and add a correction comment before continuing.
 
+For HWLAB v0.2 Code Agent context-loss or multi-turn continuity issues, the minimum closeout is a real `hwlab-cli client agent` two-turn E2E from `G14:/root/hwlab-v02` or another approved G14 execution plane with locked runtime namespace/lane env. Submit the first turn, poll its result to completed, submit the second turn with the same explicit `conversationId`/`sessionId`/`threadId`, then capture `trace`/`inspect` evidence. Passing evidence must show the second turn used prior-turn context, and should include context attachment or run reuse labels such as `conversation-context:attached`, `agentrun:run:reused`, `agentrun:runner-job:reused`, plus the relevant run/command ids. Long verification evidence belongs in a separate `gh issue comment create --body-file` comment; lifecycle close comments stay short, as defined in `docs/reference/cli.md`.
+
 `/health/live` revision is owned by `hwlab-cloud-api`; it can legitimately differ from the source commit for a Cloud Web-only change. Do not call that difference a failed Cloud Web rollout when `webAssets.checks.htmlOk`, `webAssets.checks.appJsOk`, CSS probes, Argo health, and `hwlab-cloud-web` Deployment readiness have passed. For Cloud Web behavior changes, the public JS asset probe or a bounded browser/DOM check is stronger evidence than cloud-api `apiRevision`.
 
 Do not turn `v0.2` expansion governance into a stack of broad compatibility gates. The stable control points are branch, dedicated CI/CD source repo, git mirror/relay refs, GitOps branch, namespace, runtime path, Argo Application, FRP ports and generated-output ownership. Legacy DEV/D601/main preflights that block the `v0.2` lane should be removed from that lane, not patched with fallback or legacy modes. Naming, RBAC scope, cleanup policy, resource quota and rollback order are design decisions or runbook entries unless they protect a concrete high-value risk that cannot be enforced by the fixed boundaries above.