Merge pull request #2066 from pikasTech/fix/2060-pikaoa-test-target-async

修复 PikaOA 测试启动长连接阻塞

docs/MDTODO/details/pikaoa-enterprise-platform/R1.5.9.1_Task_Report.md

@@ -0,0 +1,34 @@
+# R1.5.9.1 任务报告
+
+## 交付
+
+- Issue：[pikasTech/unidesk#2060](https://github.com/pikasTech/unidesk/issues/2060)。
+- PR：[pikasTech/unidesk#2066](https://github.com/pikasTech/unidesk/pull/2066)。
+- 实现提交：`0a580644`、`9800ca5c`；分支已吸收运行面补正并基于最新目标基线推进。
+- 关联运行面补正 [#2056](https://github.com/pikasTech/unidesk/pull/2056) 已进入 `master`，本修复覆盖 PostgreSQL、迁移 Job、API 和 Worker 的完整启动链。
+
+## 结果
+
+- `start --confirm` 只提交由 `target/instance` 唯一定位的远端任务并立即返回 `start-submitted`、`jobId`、namespace 和 `mutation=true`。
+- 同一 `target/instance/commit` 重入只解释已有状态；实例改用其他 commit 返回 `start-instance-conflict`，不创建并行任务。
+- `status` 用 YAML 声明的短 request timeout 返回运行中、成功、失败、取消和不存在状态，并包含阶段、时间、终态 code、exit code 与有限事件尾部。
+- `taskState.statusRequestTimeoutSeconds` 与 `taskState.logTailLines` 只校验正安全整数，不再由代码硬编码 30/100 策略上限；fixture 以 31/101 验证 YAML 数值可直接渲染。
+- namespace 或资源查询失败分别提升为顶层 `runtime-query-failed`、`runtime-resource-query-failed`，同时用 `taskCode` 保留启动任务状态；JSON 与默认文本输出均可见。
+- `stop` 保持 namespace 精确归属检查，运行任务通过 `startTaskDisposition` 披露取消处置。
+- 状态目录不保存 Secret、DSN、manifest 正文或命令 stderr；含 Secret 的 owner-only runner 启动后立即删除，临时 manifest 在终态清理。
+- 配置、版本与 OTel 一致性仍是 `blocking=false` warning；apply、迁移、rollout 和运行面查询的实际失败保持失败终态。
+
+## 验证
+
+- `bun --check scripts/src/pikaoa-test-target.ts`：通过。
+- `bun test scripts/src/pikaoa-test-target-async.test.ts`：2/2 通过。
+- fixture 覆盖：不存在、运行中、成功、迁移失败、重复重入、stop 取消、namespace 查询失败、资源查询失败、默认文本可见和 Secret/DSN 不泄露。
+- `bun scripts/cli.ts check --syntax-only`：11/11 通过。
+- validation-only 原入口：`configured=true remoteQueried=false mutation=false`，未调用远端 capture。
+- `git diff --check`：通过。
+
+## 边界与剩余风险
+
+- 未登记或猜测真实测试 target，未连接集群，未修改正式 CI/CD、生产配置或公网暴露。
+- 当前没有获准的专用测试 target，因此没有真实 target-side 运行证据；首次 YAML target 登记和原入口验收继续由 #2058 负责。
+- 运行中判断复用单一远端状态目录与 PID，没有新增租约、第二状态库或控制器。主机硬重启等极端中断由 `start-worker-missing` 显式暴露，不自动重放 mutation。

docs/MDTODO/pikaoa-enterprise-platform.md

@@ -92,6 +92,9 @@
 #### R1.5.9 [in_progress]
 
 落实用户最新要求：PikaOA 可不经过 CI/CD，由 YAML-first 在专用测试集群启动临时 Kubernetes 做测试和调试；SPEC 分离正式发布与临时测试，登记并验收真实 target，执行记录见 [pikasTech/unidesk#2058](https://github.com/pikasTech/unidesk/issues/2058)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9_Task_Report.md)。
+##### R1.5.9.1 [completed]
+
+将 `pikaoa test-target start` 的 PostgreSQL、迁移和 rollout 长等待改为提交即返回与 `status` 短轮询，保持真实失败可见和 Secret 脱敏，执行记录见 [pikasTech/unidesk#2060](https://github.com/pikasTech/unidesk/issues/2060)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9.1_Task_Report.md)。
 ### R1.6
 
 审核并合并双仓 PR，执行首次受控 PaC bootstrap，由正常 source PR merge 自动发布，依赖 R1.3-R1.5，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6_Task_Report.md)。

docs/reference/pikaoa.md

@@ -24,6 +24,16 @@ bun scripts/cli.ts pikaoa test-target stop --target <id> --instance <run-id> --c
 - `start` 和 `stop` 只在显式 `--confirm` 后执行。
 - `--config <path>` 可用于 fixture 或本地 override；`validationOnly=true` 的 target 永远不连接 route。
 - 默认输出是紧凑文本；`--output json` 或 `--json` 输出单一 JSON 文档。
+- 长启动使用提交与短轮询分离的远程任务：
+  - `start --confirm` 只提交由 `target/instance` 唯一定位的启动任务，返回 `start-submitted`、`jobId`、namespace 和 `mutation=true`；
+  - 相同 `target/instance/commit` 重复提交只返回已有任务状态，不再启动并行任务；
+  - 相同 `target/instance` 改用其他 commit 时返回 `start-instance-conflict`，操作者应使用新 instance；
+  - `status` 返回 `running/succeeded/failed/canceled`、当前阶段、时间、终态 code、exit code 和有界事件尾部；
+  - `status` 的运行面查询只使用 YAML 声明的短 request timeout，不进入启动等待循环。
+- 远程任务事实只保存在 target YAML `taskState.rootPath` 对应的单一状态目录：
+  - `taskState.statusRequestTimeoutSeconds` 控制短查询预算；
+  - `taskState.logTailLines` 控制事件尾部上限；
+  - 不建立第二数据库、控制器、租约或独立锁服务。
 
 ## 临时运行面
 
@@ -34,6 +44,7 @@ bun scripts/cli.ts pikaoa test-target stop --target <id> --instance <run-id> --c
   - `pikaoa.unidesk.io/target=<target-id>`；
   - `pikaoa.unidesk.io/instance=<run-id>`。
 - `stop` 删除前重新校验 target、instance 和 managed-by 标签，只删除精确实例 namespace。
+- `stop` 发现同一实例的启动任务仍在运行时，先写入精确任务的取消请求，再删除 namespace；返回 `startTaskDisposition` 说明是 `cancel-requested`、`cancel-already-requested`、`already-terminal` 或 `not-found`。
 - 正式 namespace 保护集合来自以下 YAML 字段：
   - `delivery.targets.*.namespace`；
   - `delivery.targets.*.ci.namespace`。
@@ -58,6 +69,8 @@ bun scripts/cli.ts pikaoa test-target stop --target <id> --instance <run-id> --c
 
 - Secret 值只从 YAML `sourceRef` 读取并写入目标 Secret。
 - CLI 输出只显示 `sourceRef`、`targetKey`、presence 和 fingerprint，始终保持 `valuesPrinted=false`。
+- 含 Secret 的 runner 文件使用 owner-only 权限，运行后立即删除；manifest 只在 runner 的临时目录存活，终态前由 trap 清理。
+- 状态和事件只记录公开 ID、阶段、typed code 和时间，不保存命令 stderr、DSN、manifest 正文或 Secret 值。
 - Secret 缺失会在连接测试集群前阻塞 `start`。
 - API 和 Worker 从同一 Secret 挂载严格的 PikaOA runtime YAML。
 - OTel endpoint、Prometheus scrape、指标路径和探针全部由 target YAML 声明。