pikasTech-unidesk/docs/MDTODO/observability-trace-reliability.md

# 可观测性与 Trace 可靠性 MDTODO

范围：长期跟踪跨服务 OTel trace context、业务 trace 与诊断 trace 隔离、Span Link、诊断重复性和 trace 证据稳定性。单个故障或 GitHub issue 作为 MDTODO ITEM 进入本文件，不为一次性 trace 或根因新建 MDTODO FILE。


## R1 [in_progress]

解决 [UniDesk #1801](https://github.com/pikasTech/unidesk/issues/1801)：隔离业务 trace 与 diagnostic trace，使诊断读取保持可观测但不再向被诊断业务 trace 补记 span；不得通过静默过滤隐藏真实 span，不改变已验收的纯 Kafka + SSE 实时/刷新链路，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1_Task_Report.md)。

### R1.1 [completed]

冻结 [#1801](https://github.com/pikasTech/unidesk/issues/1801) 的 trace-context 合同：业务 trace 只承载原业务执行证据，diagnostic trace 使用独立 traceId，并通过 OTel Span Link 和明确关联字段引用目标 trace；定义跨 UniDesk/AgentRun 的 propagation、采样、错误和兼容边界，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.1_Task_Report.md)。

### R1.2 [in_progress]

依赖 R1.1，执行 [AgentRun #302](https://github.com/pikasTech/agentrun/issues/302) 与 [UniDesk #1805](https://github.com/pikasTech/unidesk/issues/1805)：修改 request-scoped diagnostic context 与相关 instrumentation，使 command/result/events 读取不继承目标业务 trace 的 active parent，同时保留独立诊断 trace、Span Link、businessTraceId/commandId 关联和有界 CLI 可见性；禁止新增 terminal authority 或 Kafka event，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.2_Task_Report.md)。

### R1.3

依赖 R1.2，用固定 warm-session trace 验证重复诊断不改变原业务 trace 的 terminal/instrumentation 判定，诊断 trace 仍完整可查；补跨服务合同和端到端验收，确认实时、刷新回放及纯 Kafka + SSE 事件顺序均无变化，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.3_Task_Report.md)。

## R2 [completed]

调查第二轮业务 trace `trc_9352107b5e8a4125` / session `ses_d4473d6c-4d7a-4612-a102-254977698bc2` 的文件编辑、`apply_patch` 与 tool event 可见性：先解析对应 OTel trace/run/command，再对照 codex stdio notification、AgentRun durable events、`agentrun.event.v1`、`hwlab.event.v1` 和 HWLAB trace/read model，并使用受控的集群内或应用侧 CLI 执行 Kafka replay 校对，判定事件是源头未产生、AgentRun 映射遗漏、Kafka 转换丢失还是 HWLAB 投影丢失；不得手写 Kafka API、不得用重放追加产品 topic event、不得把投影滞后改写成业务失败，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R2_Task_Report.md)。

## R3 [completed]

解决 [UniDesk #1923](https://github.com/pikasTech/unidesk/issues/1923)：提高 CI/CD 自动链错误暴露能力并接入 OTel，覆盖 GitHub webhook→Gitea snapshot→PaC→Tekton PipelineRun/TaskRun/step→artifact/GitOps→Argo/runtime/health 的 trace context、阶段 span、首断点与脱敏错误投影；让 cicd status、PaC status/history/debug-step 和 sentinel control-plane status 默认有界显示 traceId/error code/phase/exit/下钻。exporter、版本或 commit 漂移只能非阻塞 warning；禁止新增人工交付路径、第二 authority、锁/租约/证据链/状态机，以真实失败 hwlab-web-probe-sentinel-nc01-6gjzl 和新 PR merge 自动事件验收，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3_Task_Report.md)。

### R3.1 [completed]

基于 PR #1925 合并后的真实自动事件继续修复 OTel 运行面：禁止 PaC Repository 参数未就绪时把花括号占位符作为 endpoint；从 owning YAML 在 source snapshot 内解析 OTel 配置并保留 300ms 非阻塞策略，增加安全的原始 fetch cause 投影；恢复 Tempo endpoint 后，用新的普通 PR merge 自动事件证明 collector 接收且 Tempo 可按 traceId 查询，禁止人工触发 PipelineRun，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.1_Task_Report.md)。

### R3.2 [completed]

基于真实自动事件 `hwlab-web-probe-sentinel-nc01-bbjv2` 修复 BuildKit daemon 已启动但 readiness 重试提前耗尽的竞争，并让 PaC `history/debug-step/status` 从失败 TaskRun 日志默认有界投影 traceId、首断点、阶段、error type/code/exit 与精确下钻；不得以人工 PipelineRun、锁/租约或吞掉失败缓解，使用下一次普通 PR merge 自动事件证明业务成功且 Tempo 可按同一 traceId 查询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.2_Task_Report.md)。

### R3.3 [completed]

基于真实自动事件 `hwlab-web-probe-sentinel-nc01-czhg5` 修复 `moby/buildkit:rootless` 启动合同：显式通过 RootlessKit 启动 buildkitd，保留 socket + worker readiness、有界 TERM/KILL/wait 与 typed 失败投影；禁止退回短连接重试、人工 PipelineRun 或第二 authority，使用下一次普通 PR merge 自动事件证明 image build、GitOps/Argo/runtime 成功且 Tempo 可按同一 traceId 查询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.3_Task_Report.md)。

### R3.4 [completed]

独立溯源 Web Probe Sentinel CI 从历史可成功构建到连续 BuildKit readiness 失败的首个回归：对齐成功/失败 PipelineRun、镜像 digest、TaskSpec、节点环境与 Git 提交/PR/作者，区分环境启动变慢、官方 daemonless 默认重试窗口不足和 PR #1939 裸 buildkitd 新回归，输出可复核的时间线与责任变更，不修改运行面或人工触发 PipelineRun，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.4_Task_Report.md)。

## R4 [in_progress]

解决 [AgentRun #352](https://github.com/pikasTech/agentrun/issues/352)、[HWLAB #2525](https://github.com/pikasTech/HWLAB/issues/2525) 与 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949)：消除 trace trc_f389d0493c0c489e 的 Kafka outbox 队头阻塞与 17 分钟伪耗时，恢复 agentrun.event.v1→transactional projector→hwlab.event.v1→实时/回放 SSE 单一权威；禁止 HTTP 补链、页面轮询、读侧修复、进程内 finalizer、双 authority、额外锁/租约/状态库或降低 Kafka/SSE 能力，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4_Task_Report.md)。

### R4.1 [in_progress]

执行 [AgentRun #352](https://github.com/pikasTech/agentrun/issues/352)：按 key 保序、跨 key 有界并行排空 transactional outbox，保留 durable at-least-once 并补 backlog/oldest/rate/typed error 可见性，以 NC01/nc01-v02 真实积压归零和新事件实时发布验收，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.1_Task_Report.md)。

### R4.2 [in_progress]

执行 [HWLAB #2525](https://github.com/pikasTech/HWLAB/issues/2525)：恢复固定 group transactional projector、原子 facts/checkpoint/browser outbox、hwlab.event.v1 relay 与同 cursor 实时/回放 SSE；耗时取 canonical 时间，禁止 direct/live 双写、HTTP 补链和页面轮询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.2_Task_Report.md)。

### R4.3 [in_progress]

执行 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949) 与 [UniDesk #1981](https://github.com/pikasTech/unidesk/issues/1981)：删除 config/hwlab-node-lanes.yaml、renderer、runtime GitOps 和 CI/CD 中对 Workbench 数据 authority、direct/live/refresh、projector/outbox/realtime 的架构选择与六个布尔 env 硬门禁；HWLAB v0.3 固定纯 Kafka transactional projector→outbox→实时/回放 SSE，YAML 只保留 broker/topic/group/tuning 与产品功能配置，schema 校验仅 warning 且不阻塞滚动上线，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.3_Task_Report.md)。

### R4.4 [in_progress]

依赖 R4.1-R4.3，主代理完成 PR 架构审核、顺序合并、自动 CI/CD 和 NC01/v03 原 Workbench 新 hi turn 验收；核对 command/run 实际耗时、Kafka backlog/lag、运行中增量、terminal/final、刷新 replay、公开 result 与 OTel 一致后收口，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4_Task_Report.md)。

#### R4.4.1 [in_progress]

执行 [HWLAB #2527](https://github.com/pikasTech/HWLAB/issues/2527)：修复 HWLAB PaC source artifact 未吸收 UniDesk owning YAML transactional projection authority 的漂移，以新的正常 PR merge 自动生成 direct/live/replay=false、projector/outbox/realtime=true 的 GitOps manifest；禁止手工 PipelineRun、mirror sync、Argo refresh 和运行面 patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.1_Task_Report.md)。

#### R4.4.2 [in_progress]

执行 [UniDesk #1959](https://github.com/pikasTech/unidesk/issues/1959) 及其后续解阻任务：修复 HWLAB PaC source artifact 的 runtime GitOps helper、ARG_MAX、marker 与 overlay 投影问题，并按最新 R4.4.2.10/R6 合同删除六个架构 env 及其 CI 硬门禁；大段逻辑继续使用 repo-native 文件或等价受管制品，产品 schema 失败只 warning 并继续滚动上线，禁止手改生成物、HTTP 补链、页面轮询、第二 authority 和人工 PipelineRun/同步/刷新/patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2_Task_Report.md)。

##### R4.4.2.1 [in_progress]

执行 [UniDesk #1963](https://github.com/pikasTech/unidesk/issues/1963)：修复 HWLAB runtime GitOps scripts ConfigMap 的 Git-backed 自动 ownership/交付漂移，只由正常 PR merge 自动事件验收；保持 `UNIDESK_RUNTIME_GITOPS_OVERLAY_FILE`、纯 Kafka transactional projector 与实时/回放 SSE，禁止 B64 回退、HTTP 补链、轮询、第二 authority、人工 PipelineRun/ConfigMap apply/运行面 patch及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.1_Task_Report.md)。

##### R4.4.2.2 [in_progress]

执行 [HWLAB #2530](https://github.com/pikasTech/HWLAB/issues/2530)：增加 repo-owned PaC 回归验证 `UNIDESK_RUNTIME_GITOPS_OVERLAY_FILE`、禁止 B64 内联并校对 ConfigMap mount/helper 合同，以正常 v0.3 PR merge 触发真实自动交付；保持纯 Kafka transactional projector 与实时/回放 SSE，禁止空提交、人工 PipelineRun/同步/刷新/运行面 patch及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.2_Task_Report.md)。

##### R4.4.2.3 [in_progress]

执行 [UniDesk #1967](https://github.com/pikasTech/unidesk/issues/1967)：修复 runtime GitOps postprocess 仅 JSON.parse 而跳过真实 YAML workload，使用结构化 YAML API 覆盖普通、多文档与 List 并显式写入六项 `false,false,false,true,true,true` 能力 env；只由正常 PR merge 自动交付和新 HWLAB merge 验收，禁止放宽 required boolean、手工 patch/补跑/同步/刷新及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.3_Task_Report.md)。

##### R4.4.2.4 [in_progress]

执行 [UniDesk #1968](https://github.com/pikasTech/unidesk/issues/1968)：对齐 runtime GitOps guard 的 typed `continuing/no-build-no-rollout-plan-gitops-verify` 与 PaC terminal evaluator，保持普通 skip 与 verify 模式显式分离且缺证据 fail closed，使 status/history/debug-step 同构；禁止按 TaskRun 成功启发式放宽、人工补跑/同步/刷新/patch及额外状态库锁租约，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.4_Task_Report.md)。

##### R4.4.2.5 [in_progress]

执行 [HWLAB #2532](https://github.com/pikasTech/HWLAB/issues/2532)：修复 prepare-source 仍期待 `require.resolve("yaml")` 的过期测试，结构化验证 CI node dependency bootstrap、renderer dependency-install-disabled 与 runtime GitOps helper 的 YAML 模块可解析合同，跑通全文件测试并以正常 v0.3 PR merge触发最终自动验收；禁止运行时 npm install、B64、手改生成物、空提交及人工补跑/patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.5_Task_Report.md)。

##### R4.4.2.6 [in_progress]

执行 [UniDesk #1971](https://github.com/pikasTech/unidesk/issues/1971)：修复 runtime GitOps verify guard 保留旧 `!willRunGitopsPromote` 条件导致 typed continuing marker 永不发出的合同缺口，使无 build/rollout plan 与继续 verify 正交并让 status/history/debug-step 精确返回 runtime-gitops-verify/valid=true；禁止放宽 evaluator、人工补跑/同步/刷新/patch、第二 authority及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.6_Task_Report.md)。

##### R4.4.2.7 [in_progress]

执行 [HWLAB #2534](https://github.com/pikasTech/HWLAB/issues/2534)：在 UniDesk #1972 自动交付后用受控 source-artifact renderer 重新生成 HWLAB NC01/v03 PaC artifact，使无 build/rollout plan 的 typed continuing marker 与 `willRunGitopsPromote` 解耦，并以正常 v0.3 PR merge 验证 runtime-gitops-verify/valid=true；禁止手改生成物、空提交、人工补跑/同步/刷新/patch、放宽 evaluator及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.7_Task_Report.md)。

##### R4.4.2.8 [in_progress]

执行 [UniDesk #1973](https://github.com/pikasTech/unidesk/issues/1973)：修复 PaC evaluator 对 runtime GitOps verify 真实 marker 组合的误判，允许零运行时变更 plan 下 collect-artifacts skip 与 gitops-promote continuing 共存，同时继续拒绝 promote skipped/continuing 冲突、非零 plan 与终态证据缺失；由正常 PR merge 自动交付后只读复核 `runtime-gitops-verify/valid=true`，禁止人工补跑、同步、刷新、patch及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.8_Task_Report.md)。

##### R4.4.2.9 [in_progress]

执行 [UniDesk #1975](https://github.com/pikasTech/unidesk/issues/1975)：修复 runtime GitOps scripts ConfigMap 丢失 owning YAML `codeAgentRuntime` overlay 导致 postprocess 静默未写纯 Kafka capability env、cloud-api CrashLoop 的问题，并让 verify 在工作负载未命中或 transactional projection capability/env 不完整时 fail closed；以正常 PR merge 自动链和新的 HWLAB source merge 验证 Pod ready、Argo `Synced/Healthy`、projector/outbox/realtime health 归零，禁止人工补跑、同步、刷新、patch及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.9_Task_Report.md)。

##### R4.4.2.10 [in_progress]

执行 [HWLAB #2538](https://github.com/pikasTech/HWLAB/issues/2538) P0 架构纠偏：确认 PR #2540 把已工作的 agentrun.event.v1→hwlab.event.v1→实时 SSE/Kafka retention 回放错误替换为强制 PostgreSQL transactional projector，构成重大架构偏移；从最新 v0.3 分析偏移提交并创建新的精确纠偏提交，恢复 direct publish、live Kafka SSE、Kafka refresh replay 及其单一 Kafka authority，删除强制 v8 schema 启动门禁和数据库迁移依赖，保留 canonical duration 修复、feature-config schema、HTTP fallback 禁令及其他无关改动；通过新 PR 和自动 PaC/GitOps/Argo 上线后校对实时、回放、terminal/final 与 canonical duration，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.10_Task_Report.md)。