qinglong/docs/adr/ADR-0535-canonical-panel-run-control.md

# ADR-0535：现有面板的规范 Task/Run 执行管理

- 状态：Accepted（D-433 原始源码主 CI 已通过；增强组合门发现运行中日志缺陷，修复待 Linux 验证）
- 日期：2026-09-04
- 关联：QL-RFC-0001 D-433、ADR-0530、ADR-0531、ADR-0534

## 背景

现有面板已可登录、查看定时条目和定时执行日志，但不能实际管理运行。旧 Cron 的运行状态与 ID 不是 3.0 Task revision 或 durable Run authority；直接恢复旧运行/停止按钮会混淆定时绑定版本、当前任务版本，以及多个并发运行。

## 决策

- Local capability v1 增加可选 `panel.runControl: task_run_v1`。缺省保持旧只读体验，未知值拒绝，旧客户端可忽略新增字段。`cronList=bounded_read_only` 和 `legacyMutations=false` 不变：不开放旧 Cron 写接口、Task 编辑、Trigger 编辑、批量操作或其他旧页面。
- 定时行新增“执行管理”，复用当前 Ant Design 页面和同源 API。在确认前读取 Task 当前 revision/content digest，分别展示定时绑定版本和本次运行版本；显式确认后才 POST `/api/v3/projects/:project/tasks/:task/runs`，不自动重绑 Trigger。
- Run 浏览复用规范项目 keyset API，每个显式动作至多读取 64 条并仅展示当前 Task 的匹配项。页内及跨页顺序、重复条目、next cursor 和 canonical ID 均校验；翻页替换窗口，没有总数扫描、全文累积、自动查找或轮询。空页不证明更早没有匹配运行。
- 必须读取并选择具体 Run 才能请求取消，取消 POST 指向该 Run，不按 Cron 或“最新一次”猜测目标。取消 receipt 只证明请求已登记；运行终态仍以手动刷新后的 durable projection 为准。
- 手动启动返回的 Run 可直接选择、刷新并读取 latest Attempt 首片日志；不使用定时 Trigger 匹配，以免看错另外一次运行。Edge 16 KiB、Standalone 32 KiB，日志不累计或轮询。
- 每份确认绑定一个 mutation UUID、确切版本或 Run ID。传输结果不明时保留原确认，显式重试复用同一请求体；禁止并发确认，不静默创建另一份启动请求。关闭或重连不撤销已发送的服务端操作。
- 新客户端使用不含 credential 的连接代次和窗口生命周期标记，关闭、登出或同 credential 重登后的响应不得继续产生操作。凭据仍只保留内存，不写 URL、Cookie 或 Web Storage；服务端 `run.start`/`run.stop` Policy、audit 与 mutation fence 不变。
- 新模块位于 `src/components/qinglong3`，避免 Umi 将辅助模块注册为独立页面。不新建 package、依赖、listener、timer 或数据库权威；默认 headless 和 Cluster 不携带这个 Local 面板。

## 验证与边界

客户端测试执行真实 TypeScript 模块，覆盖确认前无 POST、current revision 与旧 pin 区分、实际规范 body parser、相同 mutation 重试、并发确认拒绝、权限/版本错误、错误 receipt、准确 Run 取消、分页顺序和预算、关闭/重登、延迟解码、明确 Run 日志与新旧 capability 兼容。

客户端专项 14/14、Local API 130/130，最终后端 1700 项（1698 pass / 2 环境条件 skip / 0 fail）；Local image 与 18-package boundary audit 均 compatible。真实 Chromium 在构建后的裁剪面板和合成服务上完成登录、版本 1/2 差异展示、确认运行、选中返回 Run、读取该次日志、确认取消与 cancelled 展示。服务记录只有一个启动 POST 和一个针对相同 Run 的取消 POST；整个交互期间只有一次 Cron 列表和一次项目 Run 列表，没有后台轮询。桌面 1280 与手机 390 宽度截图复核了弹窗滚动、表格横向窗口与底部关闭入口。上述浏览器证据不包含真实执行进程或数据库写入。

Node 20 legacy migration toolchain 的 production panel build 通过；裁剪包为 240 files / 11,993,647 bytes，仍在 256 files / 13 MiB 边界。全量前端 TypeScript 检查存在 41 项错误；通过 compiler host 读取提交前源码作对比，确认本次没有新增诊断，不将存量类型错误称为通过。

本切片不是完整旧面板迁移：任务/定时创建编辑、脚本、订阅、环境变量、依赖与多用户远程 Web 会话仍未闭合。Local 仍仅 loopback/SSH tunnel；不可将本地 mock 或 unit tests 当成实际 Owner 写入、公开发布或双架构镜像证据。D-431 实物不含本切片，交付必须绑定自己的 source revision。

## 真实客户端组合验收

已有 `ql3-local-api-cancellation-live-contract` 不再手写面板启动与取消请求，而是在宿主机将实际 `src/utils/qinglong3.ts` 和 `src/components/qinglong3/runControl.ts` 编译为临时测试模块，在同一个隔离 Linux 网络命名空间中使用真实 fetch 连接生产 Local API。记录两个源文件的 SHA-256；TypeScript、VM 适配器与生成模块均不进入产品制品，不新增 workspace package 或生产依赖。

验收顺序为未认证请求 401、实际 capability discovery、读取 Task 当前版本、确认前零写入、启动一次、SQLite/PID start identity 核对、运行列表与指定 Run 读取、运行中日志标记、取消响应已被服务端接受后模拟丢失、同一客户端 action 精确重试、进程退出、唯一取消事件与两条 allowed audit、有序重启后读取 cancelled 及原日志。等待仅属于测试驱动，不在页面中增加轮询。

报告升级为 `schemaVersion=2`，要求客户端源摘要、日志/重启日志、响应丢失和相同 body 重试事实，以及一次 start POST、两次 cancellation POST。旧 v1 报告不能代替新门；原 Linux、128/256 MiB、64/256 PID、SQLite 完整性和精确事件计数要求保持不变。报告明确固定 `browserRendering=false`、`ownerProvisioning=seeded_fixture`，不能声称已经完成浏览器渲染、真实 Owner 初始化、任务创建或定时配置全链路。

本地专项回归 21/21，完整后端 1704 项（1702 pass / 2 条件 skip / 0 fail）；Local image 与 18-package boundary audit 均通过。沙箱内完整回归因 loopback `EPERM` 失败后，在允许本机端口的环境完成上述重跑，不将首次失败算作通过。本机 Docker Engine 不可连接，官方启动/恢复尝试未成功，因此新增 Linux 客户端组合门尚未执行；原有 CI amd64/arm64 Local image job 将继续执行此门，不以单元测试替代。

## 远程 CI 与整分钟边界回归

原始面板执行管理提交 `e4ba5d405f55543dd5d3ca432c24648171ebdda4` 的主 CI [33802395394](https://github.com/whyour/qinglong/actions/runs/33802395394) 已成功；它不包含后续 `e684a6e6` 的真实客户端组合验收增强。

同一原始提交的 Console 流水线 [33802432083](https://github.com/whyour/qinglong/actions/runs/33802432083) 中 PostgreSQL 18 x64 job `100804888235` 失败于 `postgres.integration.test.cjs` 的双副本调度测试：首次 `initialized` 合计为 0、期望 1。该夹具将 Trigger 时间设为观察时间前 999 ms，又使用整分钟对齐的 evaluator；在 :00 附近首次调度会合法得到 `admit`，而不是 `initialize`。本地直接执行真实 `resolveLocalScheduleDecision` 已复现这一断言失败。

修正仅将这个副本/lease 测试注入的 evaluator 改为相对一分钟，避免日历边界决定测试阶段；后续仍通过 PostgreSQL 明确置 due，保持两个副本只接纳一次、一个 Run/两个事件及过期 claim 接管断言。新增覆盖分钟偏移 0、1、999、1000、59999 ms 的回归，确认初始化与显式 due admission 分离；不修改生产 croner、misfire、数据库时钟或 claim fence。相关本地 20 项通过，真实 PostgreSQL 集成因无服务跳过 1 项，仍须由远程 CI 验证；不得将旧失败 run 改记为通过。

后续 `eaf1370c` 主 CI [33804738059](https://github.com/whyour/qinglong/actions/runs/33804738059) 的 PostgreSQL 18 x64 job 已通过，但 arm64 后端 job `100812384844` 暴露验收步骤改名回归：Local Operator 静态审计按稳定步骤名校验 gate 顺序，改名导致 `LOCAL_OPERATOR_CI_GATE_ORDER_DRIFT`。此前全量本地回归发生在工作流步骤改名之前，因此不能作为最终提交全绿证据。修正恢复原步骤名，仅增加说明实际客户端验收的注释；不放宽审计、不改变执行内容。最终工作流状态下专项 12/12、完整后端 1704 项（1702 pass / 2 条件 skip / 0 fail）及 Operator image audit 均通过，仍需新 CI 终态证明。

## 中间包检查，不构成交付

`e4ba5d40` 的 Console 流水线虽然存在上述 PostgreSQL 失败，amd64 artifact `9912447836` 与 arm64 artifact `9912402613` 已上传。两份实际下载物的 `SHA256SUMS`、bundle v8 离线审计通过；archive SHA-256 分别为 `0a8a7ba60acc4753c3889fe18255adfd2cf8fde696814a066df87e7618282f2b`、`4d6b87c4822258233ff977bac36a09064a2c4e90df6a20ccb1d86af20d3fd583`。

两架构最终 Application layer 的原生 `console.js` 均为 82,521 bytes，SHA-256 `dfcba011a165743052fe290e4f4c6b6b90074fde8dec20392252100332a6eaed`，与该 source revision 逐字节相同，包含会话隔离修复；Crontab chunk 为 76,500 bytes，SHA-256 `16f7f79622947024b84c7bd43c74b81841a2372d90a09864e473fda863794446`，核对含 `task_run_v1`、版本确认、规范 cancellation 与 receipt 校验代码。240 文件 panel manifest 的两架构摘要同为 `923ea32ae7c08624f495e7e90aa9b37a66edfc69bbda3d971001d06cb439e842`。

这些证据只排除了“包里仍是旧页面”的问题，没有补齐浏览器端到端、客户端 Linux 组合门或成功 milestone；失败流水线的中间包不提供给用户部署，不替代 D-431 已交付阶段包。

## 运行中稀疏日志缺陷与修复

提交 `ed4ba9b817b859ca1afe8b0552116b86d90f92c7` 的主 CI [33805484737](https://github.com/whyour/qinglong/actions/runs/33805484737) 已失败。amd64 job `100816011201` 与 arm64 job `100816011278` 均在真实客户端 Edge 组合门报告 `panel reads running process log marker did not converge`，尚未进入随后取消与 Standalone 验收；此前已完成的 Console fresh Owner/终态日志检查不能替代运行中日志证明。

生产 `local-process` 启动器的 FIFO 截流器原用 `head -c`；小段输出在进程持续运行时留在工具的 stdio 缓冲区。新增回归让真实子进程写出包含 NUL/0xff、无换行的 5 字节标记，等待测试端确认实际日志文件可读后才释放退出；argv/shell 两条路径在修复前均失败（文件仍为 0 字节），不会靠增大输出或先结束进程掩盖问题。

修复仅替换已打包的 3.0 启动器采集原语并更新其审核摘要：

- Alpine/BusyBox：显式调用 `busybox dd bs=16384 count=remaining iflag=count_bytes status=none`，每次短读直接写出，按真实字节扣减余额。
- Debian/GNU：使用 `stdbuf -o0 head -c remaining`，保留 GNU head 的精确读取边界，关闭其输出缓冲。
- 启动用户代码前验证所需工具能力；不支持则退出 125，不回退到缓冲复制或逐字节系统调用。工具错误不得通过继承的 stderr 绕过日志限额；复制失败仍排空用户输出，但不发布虚假的完整截断事实，读取侧保持 unknown。
- 不增加 package、OS 安装项、每任务 Node sidecar、监听器、timer 或持久状态；两种工具组合来自现有 Linux 基础环境。`shell/ql3-launcher.sh` 属遗留路径，本次不修改。

曾评估统一使用 GNU/BusyBox `dd iflag=count_bytes`，但 GNU dd 的短读计数使原有 64 KiB 精确配额回归只保留 32 KiB，因此该候选已撤回；`fullblock` 又会重新引入等待完整块的问题。不能将两种实现当作等价。

回归还覆盖空输出、恰好上限、超出一个字节、已有日志的非整块剩余额度、余额为零有/无新输出，以及工具不兼容和复制故障。Local 与 Worker 共用启动器，因此 Worker POSIX 测试同步使用真实 GNU 工具验证；macOS 测试只替换工具查找目录并保留既有 fake identity，不声称提供 macOS 生产进程身份支持。

主 CI 的 amd64/arm64 Local image job 增加安装后 headless/Console 镜像的稀疏输出与精确字节测试，保持 128 MiB、0.5 CPU、64 PID、只读、无网络及 noexec tmpfs 条件。该测试读取镜像自身 dist/assets，只把测试代码只读挂入；原实际面板客户端 Linux 组合门及其稳定步骤名不变。修复需由新提交的 Linux CI 和后续成功产物流水线证明，不把本地结果或旧归档算作已交付。

本地最终回归：Local process + Worker 163/163（首次受限环境的 3 项 loopback EPERM 已在获准环境重跑通过）；完整后端 1705 项，1703 pass / 2 条件 skip / 0 fail；镜像/客户端专项 24/24，Worker 编译与类型检查、Local/Operator image audit、18-package boundary audit、YAML 解析与新增步骤 shell 语法检查通过。本机 Docker Engine 仍不可连接，没有本地 Linux/Alpine 成功证据。