pikasTech-unidesk/docs/report/202605/20260520_Commander.md

# 2026-05-20 指挥简报

## 范围

本文是 Code Queue 指挥官针对 GitHub issue #9、#12、#13、#14、#15、#16 的过程恢复记录。目标是在上下文压缩或指挥交接后，能快速恢复当前态势。

当前生效的指挥规则：

- 指挥官仓库固定使用 `/root/unidesk` 的最新 `master`，不得为指挥工作创建 worktree。
- 仍有未完成任务时，约每 5 分钟轮询一次。
- 每轮轮询后视情况追加简报；只有活跃/排队/完成未读、相关 commit、阻塞点或下一步发生变化时才追加。
- 完成未读任务必须先审阅，再标记已读。
- 不在 master server 上跑重型 `check`、全量 e2e 或 Playwright。
- `backend-core` 和 D601 Code Queue 的生产变更默认只在 dev 验证，除非用户明确批准。
- 简报和长期参考文档使用中文。

## 快照 2026-05-20 04:16 UTC

仓库状态：

- 指挥官 worktree：`/root/unidesk`
- `origin/master`：`3a5d60140044`（`fix: read k3s artifact labels via root ctr`）
- 写入本简报前，指挥官 worktree 除新简报文件外无其它变更。

队列状态：

- 运行中：2
  - `codex_1779247780398_1`，队列 `code-queue`：#12 后端/API trace 与 STEP 合同。
  - `codex_1779247828759_1`，队列 `frontend`：#12 前端与 dev/prod 部署验证。
- 排队中：4
  - `codex_1779248021103_1`：#13 后端/API stats。
  - `codex_1779248492207_1`：#15 PR 支持。
  - `codex_1779248052767_1`：#13 前端 stats。
  - `codex_1779248189933_1`：#14 split-brain UI。
- 完成未读：1
  - `codex_1779248781778_1`，队列 `infra`：#16 CLI 渐进式披露和 skill 注入。

诊断：

- Code Queue 仍报告 live split-brain：PostgreSQL 中存在 active task，但本地 scheduler active slot 为空；同时 scheduler heartbeat 新鲜。
- 当前推荐动作仍是 `continue-supervision`，不是 stale recovery。

## Issue 状态

- #12：两条 lane 仍在执行。前端 lane 已经推送并部署过 dev frontend health commit，随后修复了通过 root `ctr` 读取 k3s artifact label 的问题。后端 lane 仍在收口 API/data contract 和类型验证。
- #13：排在 #12 后面。
- #14：排在 frontend lane 后面。
- #15：排在 code-queue lane 后面。
- #16：Code Queue 终态为 succeeded，但指挥官审阅发现发布风险。

## 审阅记录

#16 的 Code Queue final response 声称提交了 commit `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`，提交信息为 `feat: tighten code queue supervision cli`。

指挥官在 04:16 UTC 的验证结果：

- `origin/master` 仍是 `3a5d6014004412d08efe3b83f5b7c7201ec4633c`。
- 在指挥官仓库中执行 `git cat-file -t ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 没有找到对象。
- worker 路径 `/workspace/unidesk/.worktrees/codequeue-16` 在指挥官机器上不可见。

判断：

- 暂不将 #16 标记已读。
- #16 功能方向看起来有价值，但在 commit 能从 `origin/master` 获取，或 worker 解释 final response 中 commit 不可见的原因之前，不能验收。

## 下一步

- 持续轮询 #12 后端和前端两条运行 lane。
- 继续审阅 #16，必要时派一个 follow-up Code Queue 任务恢复/推送缺失 commit，或将发布失败写入 issue。
- #12 lane 完成后先审阅，再决定是否接受 #13/#14/#15 后续任务结论。
- 后续轮询如果态势变化，继续向本文追加简报。

## 更新 2026-05-20 04:20 UTC

已检查 #16 commit `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 是否推到了其它分支，包括 `release/v1`。

结果：

- `origin/master`：`3a5d60140044`
- `origin/release/v1`：`0cf73d817f14`
- `git branch -r --contains ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`：无结果。
- `git tag --contains ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`：无结果。
- `git log --all --grep='tighten code queue supervision cli'`：无结果。

结论：

- #16 仍不能验收/标记已读。final response 引用的 commit 当前不在已拉取的任何远端 ref 中。
- 下一步继续使用 Code Queue 指挥机制，而不是指挥官本地接手实现：派 follow-up queue task 恢复/推送缺失 commit，或记录 #16 发布失败。

不符合预期的 Code Queue 行为：

- 任务进入 `succeeded` 且 judge 为 `complete`，但其声明的 commit 不能从任何远端分支拉取。
- 这是指挥官可见的验收缺陷：任务“完成”不能等同于“交付完成”，Git 远端 source-of-truth 缺失时不能接受。

长期化建议：

- 为 Git-backed delivery task 增加 Code Queue 完成后验收门禁：
  - 从 worker final response 或结构化元数据解析目标分支和 commit；
  - 对 `origin/<target-branch>` 执行 `git ls-remote` / fetch 校验；
  - commit 远端不可见时，任务应标记为 `succeeded_unverified`，或至少暴露明确验收告警；
  - 在指挥官接受或派出恢复任务之前，保持未读。
- worker prompt 和 final response 必须包含目标分支、推送 commit、远端可见性证据。

## 指挥规则新增 2026-05-20 04:22 UTC

以后每个 Code Queue 派发任务都必须显式写明目标线：

- `master`：用于主动开发和集成线。
- `release/v1`：仅用于明确批准的稳定维护修复。

worker prompt 必须包含目标分支，final response 必须报告：

- 实际推送的分支；
- 远端 commit hash；
- 该 commit 是否可从 `origin/<target-branch>` 获取。

“push to master” 或 “push current branch” 这类含糊说法不再满足指挥官派单要求。

## 更新 2026-05-20 04:22 UTC

已将指挥简报和长期指挥规则中文化并推送：

- commit：`7dd947a`
- 分支：`master`
- 内容：
  - 新增 `docs/report/202605/20260520_Commander.md`；
  - 将 `docs/reference/code-queue-supervision.md` 整体改为中文；
  - 固化“目标分支必须显式写入 prompt 和 final response”的指挥规则。

同时派出 #16 恢复任务：

- task：`codex_1779250940463_1`
- queue：`infra`
- 目标分支：`master`
- 任务目标：核实 `codex_1779248781778_1` 声称的 commit `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 为什么远端不可见；如果 worker worktree 中存在该 commit，则 rebase/merge 到最新 `origin/master` 并推送；如果不存在，则报告原因或低风险恢复最小实现。

队列态势：

- 运行中：2（#12 后端、#12 前端）
- 排队中：5（新增 #16 恢复任务后，infra 队列也有待执行任务）
- 完成未读：#16 原任务仍未读，等待恢复任务或人工审阅结论。

## 更新 2026-05-20 04:31 UTC

指挥官仓库已按单一 `master` worktree 规则快进到最新远端：

- 当前 `origin/master`：`f9b190945d5e7b53adeac29a37df22f92fc7843c`
- 提交信息：`feat: tighten code queue supervision cli`
- 来源：#16 恢复任务 `codex_1779250940463_1`
- `git ls-remote origin refs/heads/master` 已能看到同一个 hash。

#16 当前判断：

- 原任务 `codex_1779248781778_1` 仍处于完成未读，不能直接批量标记已读。
- 原任务声明的 `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 仍不是当前远端头，但恢复任务已经把等价后继实现推到 `master` 的 `f9b1909`。
- 恢复任务仍在运行，正在解释原任务为什么 succeeded 后远端不可见；等恢复任务终态后再审阅并决定是否接受原 #16。

新 CLI 的监督能力已经生效：

- `bun scripts/cli.ts codex tasks --unread --limit 10` 现在只返回完成未读任务，不再退化为全量 overview。
- `bun scripts/cli.ts codex tasks --view supervisor --limit 10` 能显示 running、completedUnread、queued 和每个任务的 drill-down 命令。
- `codex queues` 仍显示 `split-brain`，但 `splitBrainLive=true`、`effectiveLiveness=live`，heartbeat 新鲜，按长期规则继续监督。

队列态势：

- 运行中：3
  - `codex_1779247828759_1`：#12 frontend，报告实际部署已切到 `6e86d36` 且 service-proxy `/health` 确认新 commit；当前摩擦点是部署脚本定位 pod 的 selector 过旧，worker 正在修 fallback。
  - `codex_1779247780398_1`：#12 backend/API，已完成设计 pass，正在做窄范围编辑。
  - `codex_1779250940463_1`：#16 恢复，已推送 `f9b1909` 到 `master`，仍在补原因分析。
- 排队中：4
  - #13 backend/API stats：`codex_1779248021103_1`
  - #13 frontend stats：`codex_1779248052767_1`
  - #14 split-brain UI：`codex_1779248189933_1`
  - #15 PR 支持：`codex_1779248492207_1`

长期化建议：

- 部署脚本的“部署失败”判定不能只依赖单一 pod selector；如果服务健康和 live commit 已符合预期，脚本应明确区分“部署成功但验证 selector 需要 fallback”和“服务实际未部署成功”。

## 更新 2026-05-20 04:38 UTC

指挥官仓库继续保持单一 `master` worktree，并已快进到：

- 当前 `origin/master`：`f3b7d1a183800cafffb52e0cac6e118fe1e082bd`
- 提交信息：`fix: resolve k3s artifact image refs`
- 变更范围：`scripts/src/artifact-registry.ts`

队列态势仍为 3 运行、4 排队、1 完成未读：

- 运行中：
  - `codex_1779247828759_1`（#12 frontend）：已把 dev frontend 健康探针切到 `f3b7d1a`，`http://74.48.78.17:18083/health` 返回 `deploy.commit/requestedCommit=f3b7d1a183800cafffb52e0cac6e118fe1e082bd`。但定向 E2E 失败在 `codex-execution-summary-current`，说明 fixture 已进入页面但 TraceView 没显示当前 attempt 段；worker 正在判断是测试等待条件问题还是前端同步缺口。
  - `codex_1779247780398_1`（#12 backend/API）：heartbeat 新鲜，仍在 fixture-driven regression 设计和实现中。当前方向是不改大面积 UI，而是让 payload 带上类似 OA stats 的 source hint 和 sync metadata。
  - `codex_1779250940463_1`（#16 恢复）：attempt1 已完成 push/root-cause 解释，但 judge safety override 判定“源码已改但 live service 未验证”，进入 attempt2。worker 正在确认 D601 live `code-queue-backend` 的重建/重启路径，并计划验证 `/health` 和 `/api/judge/probe`。
- 排队中：
  - `codex_1779248021103_1`（#13 backend/API stats）
  - `codex_1779248052767_1`（#13 frontend stats）
  - `codex_1779248189933_1`（#14 split-brain UI）
  - `codex_1779248492207_1`（#15 PR 支持）
- 完成未读：
  - `codex_1779248781778_1`（#16 原任务）继续保持未读，等待恢复任务 attempt2 终态和 live verification 结论后再审阅。

不符合预期或需要关注的行为：

- #16 恢复任务的 attempt1 已满足“恢复缺失 commit 并解释远端不可见原因”的原始显式验收，但 judge 通过 safety override 扩展为“必须 live 部署/验证 Code Queue 运行服务”。这个方向可能是合理的，因为 #16 修改了 Code Queue CLI/API/runtime，但也说明 judge 对“恢复任务”和“上线任务”的边界识别还不够精确。
- #16 attempt2 可能触碰 D601 live Code Queue 后端。由于 heartbeat 新鲜、worker 明确在检查真实服务和 probe contract，目前不打断；下一轮重点观察是否真的执行重建、是否影响正在运行的 #12 任务，以及 restart-recovery 是否正常。

长期化建议：

- judge 对基础设施恢复任务应区分“source-of-truth 恢复验收”和“live runtime 上线验收”。如果任务 prompt 原本只要求恢复远端 commit，judge 可以提示后续上线任务，但不应无条件把它 retry 成部署任务；除非 prompt 明确要求 live service 必须消费该变更。
- 对 Code Queue 自身的 live 重启/重建必须在 final response 中报告影响范围、是否触发 restart-recovery、恢复后哪些正在运行任务仍保持 heartbeat 新鲜。

## 更新 2026-05-20 04:44 UTC

指挥官仓库已快进到：

- 当前 `origin/master`：`8df0663a925d31dffb4e39f50bbc744c06838ab8`
- 提交信息：`test: select retry trace fixture task`
- 变更范围：`scripts/src/e2e.ts`

队列态势仍为 3 运行、4 排队、1 完成未读：

- `codex_1779247828759_1`（#12 frontend）已完成 `frontend` artifact 发布：
  - commit：`8df0663a925d31dffb4e39f50bbc744c06838ab8`
  - pipeline：`user-service-artifact-frontend-20260520044225-8whsf`
  - digest：`sha256:1ff9190f3e2f024d00eedc8e0eea00ea8f5cfd7d5b9e5deecc8cc24b5058ee67`
  - 已通过 `artifact-registry deploy-service --env dev --service frontend --commit 8df0663... --provider-id D601 --run-now` 部署到 dev。
  - 当前正在重新运行三项定向 DEV E2E：`frontend:code-queue-retry-attempt-trace-current`、`frontend:code-queue-step-missing-diagnostic`、`frontend:code-queue-judge-feedback-attempt-order`。
- `codex_1779247780398_1`（#12 backend/API）仍在运行，正在检查 summary 和 step payload 两条路径，防止只修 summary 后 TraceView 仍因旧 cached transcript 复发 stale-attempt 问题。
- `codex_1779250940463_1`（#16 恢复）仍在 attempt2 运行，尝试寻找 Code Queue live 部署路径时出现：
  - `bun scripts/cli.ts ssh D601 hostname` 返回 `provider is not online: D601`。
  - `server --help` 显示 main-server `server rebuild` 只支持 `code-queue-mgr`，不支持 D601 Code Queue 执行面。
  - 当前判断：这是 #16 live verification 的潜在基础设施阻塞，但不是整个 Code Queue scheduler 死亡，因为三个 running task heartbeat 仍新鲜。

不符合预期或需要关注的行为：

- D601 provider-gateway SSH 维护桥不可用，但 D601 上的 Code Queue scheduler/runner 仍能持续写 heartbeat。说明“D601 provider online”与“D601 Code Queue 执行面活着”是两个不同健康维度；指挥官不能简单把 provider offline 判为 D601 全面掉线。
- #16 attempt2 如果必须依赖 provider SSH 重建 D601 Code Queue backend，当前可能卡住；下一轮重点观察 worker 是否找到 D601 本地/容器内可执行的受控部署路径。如果没有，可能需要拆出 provider-gateway/D601 维护桥恢复任务，或由指挥官做最小手动恢复后再继续。

长期化建议：

- Code Queue 自身的 D601 执行面部署应有不依赖 provider SSH 在线状态的本地受控恢复路径，或者至少在 `codex task` 运行容器内暴露明确的“我在 D601，可以执行本地部署/重启”的安全命令。
- 监督视图应把 provider-gateway 在线状态、scheduler heartbeat、runner heartbeat、service proxy 可达性拆成独立指标，避免“provider offline”误导为“执行面死亡”。