注释/文档声称被活代码推翻：pkg/safego「两台服务已收敛」vs 4 处手写 recover(3 处无 stack/metric) + resputil「唯一 writer」vs pkg/errcode.WriteJSON(吞编码错误) + 6 处点名不存在文件的注释 + pkg/errcode 2 个死导出

[DeliciousBuding]

来源：round-64 lane D 只读探索（#2241），锚点在 42ba064c 逐行核实。主机侧已抽验复现并修正了 1 处原报告证据不准（见切片 3 注）。

主题：注释/文档做出的收敛声明被活代码推翻。这类注释读者信任度最高，成本不是「读不懂」而是「照着做无处可放」或「以为还有一份旧实现需要对照」。

切片 1：pkg/safego 声称两台服务已全部收敛，实际仍有 4 处手写 recover（3 处无 stack、无 metric）

pkg/safego/safego.go:18-21
  // ... so those panics were invisible to every dashboard while Hub's
  // equivalent ones were counted. That copy is gone (#2154); both servers
  // now launch through here and both install an observer

被这 4 处推翻：

位置	形态
edge-server/internal/events/bus.go:441-447	手写 recover，slog.Error("event bus observer panic", "panic", recovered)，无 stack、无 metric、无 observer
hub-server/internal/ws/fanout.go:226-231	同上（ws PushToSession panic recovered）
edge-server/internal/adapters/parser_ndjson.go:56-63	同上（ndjson: panic in parseLine）
hub-server/internal/bus/bus.go:138-145	第 4 种写法：自己 metrics.EventBusPanics.Inc() + 自己记 stack，不走 safego observer

复现的正是文档自己描述的那个故障模式（edge 侧 panic 无 stack、无计数 → 对 dashboard 不可见）。4 处都能用现成的 defer safego.Recover("name")（该 API 就是为「非 go 语句、直接在闭包里 defer」设计，仓库内已有 30+ 处这么用）⇒ 不是「做不到」，是「约定没被门禁保住」。

修法：4 处替换为 defer safego.Recover("<stable.name>")；bus.go 需要的专属计数用已有的 SetPanicObserver 按 name 分派（observer 签名已带 name string，见 safego.go:39-50），不要保留私有计数器；把 safego.go:20-21 表述改准确，或加一条测试断言白名单外不存在裸 recover()。
（middleware/recovery.go、middleware/timeout.go、httpserver/server_middleware.go、handler/ws.go 的 recover 是 HTTP 请求面兜底，属正当，不计入。）写集 ≈5 文件 / 30 行。

切片 2：resputil 自称 edge「唯一 JSON response writer」，但 pkg/errcode.WriteJSON 是第三个 writer，且它吞掉编码错误

edge-server/internal/resputil/resputil.go:1-8
  // Package resputil holds the single JSON response writer for the Edge server's
  // inbound transports ... This is the converged implementation (#1675) ... so the
  // wire behavior cannot diverge again.
edge-server/internal/resputil/resputil.go:28-30
  if err := json.NewEncoder(w).Encode(v); err != nil { slog.Error("write json response failed", "error", err) }
pkg/errcode/error.go:141-143
  if v != nil { json.NewEncoder(w).Encode(v) }        // 返回值被丢弃
edge-server/internal/httpserver/server_middleware.go:24,84
  sharederr.WriteJSON(w, http.StatusForbidden/Unauthorized, ...)   // edge 实际调用 pkg 那份

声明对 internal/api + internal/mcp 成立（那两处的 writeJSON 确实是 1 行 shim），但对 edge 中间件层不成立——它在任何 transport handler 之前就用另一份实现写 401/403。漂移维度正是声明里点名的 log text：resputil 记编码失败，pkg 版静默丢弃 ⇒ 同一台服务上「响应体写坏了」这件事一半可观测一半不可观测。

修法：二选一——(a) 删 pkg/errcode.WriteJSON，server_middleware.go 两处改用 resputil.WriteJSON（pkg 不该有 HTTP writer）；或 (b) 保留但补错误日志并让 resputil.WriteJSON 转发它。同时把 resputil.go:1-8 的 "single" 改成准确范围。写集 ≈2-3 文件 / 15 行。

与 #（edge status 手抄）那条 issue 同属 edge-server 响应面，建议同一个 wave 内串行做，不要并行（会撞 resputil/errcode）。

切片 3：6 处注释点名仓库中不存在的 .go 文件，其中 1 处是「代码该放这里」的指令性注释

注释位置	点名的文件	实测
hub-server/internal/service/agentteam/route_helpers.go:14 // Keep orchestration (DB, dispatch, events) in agent_team_routing.go.	agent_team_routing.go	不存在（find 命中 0）；实际是 route_decision.go / agent_team_run.go
hub-server/internal/service/agentteam/agent_team.go:14-17 文件清单	agent_team_routing.go	不存在；且清单漏了 agent_team_compete.go/_replay.go/_review.go/assignment_lifecycle.go/audit.go/authz.go
hub-server/internal/service/deliveryoutbox/doc.go:9-11	delivery_outbox.go、delivery_outbox_model.go、delivery_outbox_facade.go	前两个不存在；第三个存在但在父包 service（hub-server/internal/service/delivery_outbox_facade.go:1），不在本包。本包实际 8 文件：outbox.go entry.go retry.go status.go eligibility.go store.go string.go orchestration.go
hub-server/internal/service/dispatchsvc/agent_dispatch_ports.go:40	delivery_outbox.go / delivery_outbox_model.go	均不存在
edge-server/internal/runnerctx/context_budget.go:5-7 // moved ... into context_budget_message.go and context_budget_compact.go. Zero behavior change — pure move only.	context_budget_compact.go	不存在（只有 context_budget_message.go）⇒ 声称的「两文件拆分」实为一文件
edge-server/internal/adapters/opencode/opencode_acp.go:4-7 // The existing OpenCodeAdapter (opencode.go, root package) is Phase 1/2 batch mode: ... a 500+ line custom parser ... This adapter replaces that hop	opencode.go + type OpenCodeAdapter	文件不存在；该包实际只有 fixture_provider.go aliases.go opencode_acp.go opencode_acp_test.go doc.go

主机侧修正：原报告称「全仓 grep -rn OpenCodeAdapter 只命中这条注释本身」，实测 4 处命中——除 opencode_acp.go:4 外还有 opencode_acp_test.go:173（注释）、:176（测试函数名 TestOpenCodeAdapterMetadataIsNotEmpty）、:198（注释 "the legacy opencode run --format json OpenCodeAdapter has none"）。核心结论不变：没有任何 OpenCodeAdapter 类型/符号定义、没有 opencode.go；但那 3 处测试侧引用说明「legacy 适配器已删」这件事在测试注释里也留了同样的过期指代，修的时候要一并处理（否则改完源码注释、测试注释仍在指向不存在的东西）。

修法：逐条改成当前真实文件名，或直接删掉易腐的文件清单（改为一句职责描述）；opencode_acp.go:4-7 把 "existing/replaces" 改成过去式并注明旧 batch 适配器已删除、同步 opencode_acp_test.go:198；deliveryoutbox/doc.go:9-11 换成真实 8 文件的职责表。写集 ≈6-7 文件 / 30 行纯注释，零行为变更、零测试影响。

切片 4：pkg/errcode 两个导出符号是死代码，其中一个是另一函数的 17 行近似副本

• pkg/errcode/error.go:119-135 WriteErrorWithTrace — 全仓 0 个调用方（含测试），是 WriteError（:95-117）的逐行复制
• pkg/errcode/error.go:152-161 EnvelopeForGin — 唯一调用方是它自己的测试 pkg/errcode/errcode_test.go:168-170；活的那份是 EnvelopeForGinWithTrace（:163-175，被 hub-server/internal/handler/response.go:39 使用）
• EnvelopeForGin（无 traceId 字段）留在 pkg/ 导出面上＝持续邀请新调用方选那个「丢掉 trace 关联」的劣化版本，而 error.go:99-100 的注释恰恰把 trace 关联当卖点

修法：删 EnvelopeForGin 及其测试；WriteErrorWithTrace 二选一——删掉，或把 WriteError 重写为 WriteErrorWithTrace(w, err, NewTraceID()) 让两者共用一份实现（后者更省事且保住 API）。写集 ≈2 文件 / 25 行删除，风险极低。

验收

• 切片 1：必须有断言/门禁证明「白名单外不存在裸 recover()」，否则这次收敛下次还会漂；edge 侧 panic 必须能记到 stack 与计数
• 切片 2：必须有断言「编码失败会被记录」（两份 writer 行为一致）
• 切片 3：纯注释，git diff --check 干净 + make test 不受影响即可；改完必须再跑一次 find 证明注释里点名的每个文件都真实存在
• 切片 4：删导出符号前必须再跑一次全仓 grep（含 _test.go）确认 0 调用方

负向约束

• 切片 1 不许把 HTTP 请求面兜底的 recover 也「收敛」掉（那是正当的）
• 切片 3 不许顺手改代码逻辑（纯注释批）
• 切片 4 不许因为「导出即承诺」就保留死代码；pkg/ 是三 module 共享层，删之前确认无外部 consumer

[DeliciousBuding]

排期依赖（round-65 主机侧登记，避免 round-66 撞写集）

本 issue 的切片 2（resputil 自称 edge「唯一 JSON response writer」vs pkg/errcode.WriteJSON 是第三个 writer 且吞编码错误）与 round-65 lane C 正在新增的 errcode.Write helper（#2245 stage1）正面冲突：lane C 会在 pkg/errcode 里新增一个 writer 并把 handlers_delivery_journal.go 的 2 处改成走它。切片 2 若同时开 lane，两边会改同一批文件、并对「到底哪个是 single writer」给出互相矛盾的答案。

⇒ 切片 2 必须等 #2245 stage1 落地后重新锚定：届时 single-writer 的事实答案可能已经变了（errcode.Write 走 resputil 编码、不再吞错误），本切片的修法要按新现状重写，不能照原文执行。

切片 1（pkg/safego「两台服务已收敛」被 4 处手写 recover 推翻）与 round-65 无文件重叠，可独立排期，写集 ≈5 文件 / 30 行，原文仍有效。

另登记一条同族新证据（round-65 主机侧实测，非本 issue 原文）：checks.yml:213-215 注释自称 shard 轮询切分「balanced and disjoint」，实测 run 33674961074 中 go-hub-test shard2 = 4m51s vs shard1 = 2m43s ⇒ disjoint 成立、balanced 被推翻。该条已归入 CI 关键路径 issue 的切片 2，此处只做同族索引，避免两处重复开工作。

[DeliciousBuding]

切片 1 已修并合入 master：41193097（PR #2264，squash，因接线 checks.yml 跑全矩阵：41 pass / 0 fail / 6 skipping，一轮过）

主机核验记录（不是 lane 转述）：

• 落地一致性：git diff 41193097 52b415cb 为空。
• 4 处收敛全部到位，grep -rn "recover()" --include=*.go hub-server edge-server pkg | grep -v _test.go 现在只剩 6 处白名单（HTTP 请求面兜底）+ pkg/safego 自身实现的 2 处。name：eventbus.handler / ws.push_to_session / events.bus_observer / ndjson.parse_line。
• eventbus_panics_total 未丢：改由 hub 的 PanicObserver 按 name 前缀 eventbus. 分派，bus 包里的私有 Inc() 已删；指标名 / label / MustRegister 一字未改，pkg/safego 导出符号集合 diff = IDENTICAL（未改任何公开 API 签名、未新增第二个 observer 机制）。
• 门禁已落地并接线（本切片的验收核心）：scripts/verify/verify-safego-convergence.py + scripts/verify/tests/verify-safego-convergence.Tests.py（14 条负向自测），接进 checks.yml 的 validate job，并在 docs/governance/verifier-map.md 登记（doc-ssot 的 verifier-map 计数由 66 scripts / 58 CI files 变 67 / 59）。白名单键 = 文件路径 + 允许命中次数（不是行号），匹配前先剥 Go 注释与字符串字面量。
• 主机独立复跑：hub internal/{bus,ws,metrics} ok（7.6s / 12.4s / 0.01s）、edge internal/{events,adapters} ok、pkg 全部 10 个包 ok；go vet 0；scoped gofmt -l 空；actionlint 前后 findings 多重集 IDENTICAL（11 条 shellcheck，SC2034×6 / SC2069×2 / SC2086×3，零新增）；verify-ci-gates.py ok + 自测 39 OK；verify-test-sleep-ratchet（47 sleeps / 21 files，与 base 一致）、quality-debt-ratchet(9 pass)、conventions、hub-layering、hub-pure-packages、orchestrator-deps、openapi-contract(153/156/3/0) 全部 rc=0。
• 主机反向验证（暗卷）：
  • (a) 把 edge-server/internal/events/bus.go 单独还原到 base → 门禁 FAILED 并精确打出多了哪一处（bus.go:454: if recovered := recover(); …）；git checkout HEAD -- 还原后复绿、git status --short 为空。附带证实：回退态连编译都过不了（未使用的 import），门禁依然红 ⇒ 它不依赖 Go 工具链，这正是能挂 validate 的理由。
  • (b) 把 bus.go 两个 defer 的注册顺序写反 → 2 红 2 绿：RecoverRunsBeforePendingDecrement 红、CountedByHubObserverNotByBus 红（eventbus_panics_total 真的丢一次 +1）、PendingReturnsToZero 绿、既有 PanicRecoveryOthersSurvive 绿。还原后 4 条全绿。

⚠️ 派活 brief 里的一处因果被 lane 用实验推翻，主机复核后确认 lane 是对的

brief 写的是「defer 顺序写反 = panic 时 pending 永久泄漏、Pending() 谎报」。这句错了：unwinding 期间被调用的 defer 照常执行完毕，两种顺序 pending 都归零（暗卷 (b) 的两条绿就是直接证据）。顺序仍然 load-bearing，但真正的后果是「总线自报 drained 时这次 panic 还没被记账」⇒ eventbus_panics_total 丢计数。代码注释已按实测结论重写，没有把错话留在仓库里。判例：brief 里写的「机制」若未实验取证，必须标注为推测，否则 lane 会照着错因果设计暗卷。

本 issue 收窄：只剩切片 2 / 3 / 4，且切片 1 追加了一处新站点

• 切片 1 追加（建议作为切片 2 的第一项）：hub-server/internal/handler/ws.go:132 的 recover 在 writeLoop 里——per-connection goroutine（同函数 :118-121 的裸 go func(){…}() 启动，就在 safego.SafeGo("ws.readLoop", …) 上方 5 行），只写一行 log、无 stack/metric/observer，与本批收敛的 4 处同一种病。本 issue 原文把 6 处白名单统称「HTTP 请求面兜底，属正当」，对这一处不成立（其余 5 处成立）。本批未动（在写集外），但也没把那句错话抄进注释：pkg/safego 包注释与 verifier 白名单的 reason 字段都点名它是「收敛候选而非豁免」。做掉它时白名单里 handler/ws.go 的允许次数要从 2 降到 1，门禁会自动逼着改（次数用不满也红）。
• 切片 2 未动，且按本 issue 自己的提示必须与 edge 要求 ~160 个调用点手抄 HTTP status，与 errcode.HTTPStatus 冲突——落 errcode.Write 单源 helper + 修 delivery_journal 2 处已实证矛盾(503/500 配 bad_request) #2245 串行（会撞 resputil/errcode）。注意 edge 要求 ~160 个调用点手抄 HTTP status，与 errcode.HTTPStatus 冲突——落 errcode.Write 单源 helper + 修 delivery_journal 2 处已实证矛盾(503/500 配 bad_request) #2245 stage1 已合，切片 2 的锚点需在其之上重新定位。
• 切片 3（6 处注释点名不存在的 .go 文件）/ 切片 4（pkg/errcode 两个死导出）未动。
• 本批顺手修掉了 3 处在 base 上就已存在的 gofmt 违规（pkg/errcode/codes.go、pkg/errcode/errcode_test.go、hub-server/tests/integration/notification_retention_test.go，纯空白零语义）——因为切片 1 的验收命令之一「gofmt -l hub-server edge-server pkg 必须无输出」在 base 上根本不可能满足（CI 绿是因为 .golangci.yml 的 paths: - tests 排掉第 3 个、而 pkg/ 不归任何 lint job）。修完该命令第一次真的无输出。

留给管理员的两个决策（本批刻意没自己拍）

1. ndjson 的 runId/seq 与 fanout 的 session_id 三个结构化日志字段随收敛丢了（safego 的 name 必须是低基数稳定 label）。不改公开 API 的保法：defer safego.RecoverInto(name, &lineErr) + 外层再一个 defer 在 lineErr != nil 时补打这两个字段（LIFO 保证 RecoverInto 先跑）。要不要这么做，或给 safego 加 RecoverWithAttrs(name, attrs...)，属独立决策。
2. hub-server/internal/metrics/metrics_test.go 的 TestEventBusCounter 断言进程级 counter 的绝对值 == 2，是个地雷（今后任何在它之前喂 eventbus.* 的用例都会误伤它）。本批采取零风险做法：新用例一律 before/after 差值断言并追加在它之后 + 注释写明顺序约束。把它本身改成差值断言属于改既有断言，超出切片范围，未做。