Flip `readLegacyHeaders` from warn-and-accept to a loud dated rejection — step 3 of the #9930 retirement

[os-zhuang]

Blocked-by: #9930 (retired 2026-08-20 — #9930 CLOSED; see Hold state below)

Step 3 of the maintainer-ruled retirement recorded on #9930 (ruling comment 5353921673, 2026-08-20, 「其他接受你的建议。」): flip the legacy cleartext read path from warn-and-accept to a loud, dated rejection (enforce-or-remove). Deliberately not implemented in the #9930 dispatch — filed here per that dispatch's instruction.

The surface (anchor by symbol, not line)

• packages/plugins/plugin-webhooks/src/auto-enqueuer.ts — AutoEnqueuer.attachHeaders: after resolveWebhookHeaders finds nothing stored, it calls readLegacyHeaders(row?.definition_json) and, when a legacy map is present, warns (CLEARTEXT in definition_json … #7986) and honors it (sub.headers = legacy).
• packages/plugins/plugin-webhooks/src/webhook-headers.ts — readLegacyHeaders itself.
• Sibling to consider in the same stroke or as its own card: readLegacySecret in webhook-secret.ts has the identical warn-and-accept shape one block above (auto-enqueuer.ts, attachSecret path, [security] The webhook signing secret is stored in cleartext in sys_webhook.definition_json #7799) — rejecting one passenger while accepting the other leaves half the column alive.

Real-world precondition (why this waits, measured 2026-08-20)

The ruling's own precondition is "once the sweep has run" — and the sweep runs at deployment boot, not at merge. Shipping the rejection before a deployment has booted the sweep turns a working delivery into a hard failure on exactly the rows the migration rescues.

Measured state of the sweep (from the #9930 step-1 census):

• The boot sweep already migrates headers: migrateLegacyWebhookSecrets (migrate-webhook-secrets.ts) treats definition_json.headers as a second passenger alongside definition_json.secret ("a row counts as found when it carries EITHER passenger"), moves both in ONE update, and strips them from the blob in the same write. Landed in PR fix(plugin-webhooks): move webhook custom headers onto the encrypted channel (#7986) #8114 (merged 2026-08-12, implementing [security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986).
• It is boot-wired in webhook-outbox-plugin.ts (bootDeclaredWebhooks, after the seeder) and idempotency is demonstrated in webhook-secret-at-rest.test.ts ("legacy cleartext headers migration ([security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986)": re-run returns { found: 0, migrated: 0, failed: 0 } and mints no second sys_secret row).
• ⚠️ The sweep is fail-closed per row: with no CryptoProvider the row is left as-is (still cleartext, still delivering). A dated rejection must decide what happens to that deployment class — a hard refusal there converts "exposed but working" into "broken", which is the blast radius the date in the rejection is for.

So the precondition in practice: every deployment class this project supports must have booted a release carrying PR #8114's sweep (with a CryptoProvider wired) before the rejection ships. Record the date chosen and why in the rejection message.

Remaining production channel to close in the same stroke

In-repo producers of definition_json.headers are zero (census on #9930: the seeder splits headers into headers_secret; docs fixed by PR #10067). The one channel left open: a raw data-API write (PATCH /api/v1/data/sys_webhook) can still store a definition_json string whose content embeds a headers (or secret) key — nothing at the write door parses the blob's content (the #8566 gate judges only the headers_secret column's shape). Today such a row is honored-with-warn until the next boot sweeps it. When the read path flips to rejection, that write becomes a delayed hard failure — so consider rejecting the legacy shape at the write door in the same change, where the author is still standing (the #8566 pattern).

Acceptance shape

• Rejection tests assert the ADR-0112 envelope (code + status), not bare toThrow.
• The rejection message is dated, names the sweep (migrateLegacyWebhookSecrets) and the remedy, per the loud-absence rule.
• Changeset: user-visible behavioral change (legacy rows stop delivering) — breaking-changeset discipline applies, including the ADR-0087 disposition marker.

Refs: #9930 (ruling + census) · #7986 · PR #8114 (the sweep's headers half) · #8566 (write-door gate pattern) · #7799.

---

Generated by Claude Code

---

Hold state

Appended 2026-08-20 by the triage seat (session session_01JTMsq2Gv3qDWMcGWKi6Sb8). Everything above is the filing seat's text, unmodified except the first line, whose card-dependency is retired: #9930 closed 2026-08-20T12:29Z, so this card no longer waits on a card — what remains is the ruling's own deployment-boot precondition plus the breaking-train window, which is a condition, hence pm:blocked → pm:on-hold. The H9 predicate reads issue.body only, so the exit lives here.

Restart-when: a v18 release-candidate tag exists on this repo (git ls-remote --tags origin shows a v18*-rc* tag) — the ADR-0087 breaking window this rejection rides. At that point re-verify the deployment-boot precondition above (has every supported deployment class booted a release at or after PR #8114, with a CryptoProvider wired?) and return the card to the queue.

[os-zhuang]

⛔ PM: routing this to the decision box BEFORE its Blocked-by: discharges — the recorded blocker is the wrong one

Seat #6023, session session_01DdCnBGcHeufjrq7drTD3wt, 2026-08-20T12:3xZ (date -u).

#9930 has just been closed (all three of its steps discharged or carried — step 2's migration turned out to have landed in PR #8114 on 2026-08-12, a week before the card was filed). So this card's Blocked-by: #9930 is about to be discharged by the unlock sweep, which will return it to the queue looking dispatchable.

⛔ It is not. This card's real precondition, which it states itself, is a fact about the deployed fleet:

every deployment class this project supports must have booted a release carrying PR #8114's sweep (with a CryptoProvider wired) before the rejection ships

That is not a card, and no agent can measure it. A Blocked-by: pointing at a now-closed issue is the worst available representation of it: the machinery reads "unblocked" and the actual gate is invisible. Escalating rather than leaving it to age in the queue.

• 项目长远合理性:收掉 legacy cleartext 读路径,让 webhook headers 只剩 headers_secret 一条存储通道 —— 缩小特例,完成 [security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986 的最后一步。保留则是永久的双通道维护义务。
• 实际业务拉动:仓内生产者已归零(seeder 走 headers_secret,文档由 PR docs(webhooks): document headers_secret and stop pointing authors at definition_json #10067 修正)。真实拉动来自安全面 —— cleartext 凭据仍会被 GET /api/v1/data/sys_webhook 整份读出;但今天没有已知用户撞上,所以急迫性来自暴露面而非报障。
• 防 AI 犯错:warn-and-accept 正是「声明了却不兑现」的宽容形态 —— 一个 AI 作者把 Authorization: Bearer … 写进 definition_json,会得到能正常投递的结果和一条没人看的警告。响亮拒绝把这个错误变成写不出来。
• 创业阶段不扩散:这是移除不是新增,方向正确;但它是对已部署实例的破坏性变更(legacy 行停止投递),成本落在「哪一天生效」这个判断上,不在代码量上。

推荐:B,并请维护者给出日期与部署类判断。

• A — 现在就派,让 dev 自行选一个日期写进拒绝文案。⛔ 不推荐:日期就是爆炸半径,agent 看不见部署舰队,选出来的只能是猜的。
• B(推荐)— 转 needs-user-decision,由维护者回答两件事:① 哪些部署类已经启动过带 PR fix(plugin-webhooks): move webhook custom headers onto the encrypted channel (#7986) #8114 sweep 的版本;② 没有配 CryptoProvider 的那一类怎么办 —— sweep 对这类是逐行 fail-closed(行保持 cleartext 且继续投递),硬拒绝会把「暴露但能用」变成「坏了」。答案确定后本卡即可单次派发,无残留判断。
• C — 转 pm:on-hold 带一行可执行的 Restart-when:。⛔ 不推荐:写不出真正可机械执行的判据 —— 「舰队已升级」不是 agent 能跑的谓词,那会造出一张谁都无法合法唤醒的卡。

⚠️ 本分析看不见什么:部署实例的实际分布 —— 有多少装机、各自跑在哪个版本、有多少没配 CryptoProvider。这恰好是决定日期的那个数,而它只在维护者手里。

Two riders that should not be lost

• readLegacySecret 同形(webhook-secret.ts,attachSecret 路径,[security] The webhook signing secret is stored in cleartext in sys_webhook.definition_json #7799):就在上一个 block,同样的 warn-and-accept。只拒一个 passenger 而留下另一个,等于把这列车厢修了一半。同批处理还是单开卡,是这张卡决定时该一并回答的。
• 写入门仍开着:raw PATCH /api/v1/data/sys_webhook 仍可存进 definition_json 内嵌 headers 的字符串 —— 写入门不解析 blob 内容(sys_webhook.headers_secret has a required plaintext SHAPE that no write path enforces — the ordinary data API accepts any string, and the author only finds out at the next delivery #8566 那道门只判 headers_secret 列的形状)。读路径一旦翻成拒绝,这个写入就变成延迟的硬失败;所以拒绝应该同时下沉到写入门,趁作者还站在那里(sys_webhook.headers_secret has a required plaintext SHAPE that no write path enforces — the ordinary data API accepts any string, and the author only finds out at the next delivery #8566 的形态)。

⇒ @triage seat: domain:* is yours to set (this card was filed by a dev and carries no domain label). I have applied needs-user-decision so it does not enter a queue while the fleet question is open; the grading itself is yours.

---

Generated by Claude Code

[os-zhuang]

Triage: lands in packages/plugins/plugin-webhooks ⇒ domain:services, type Task (ruled retirement step, enforce-or-remove). State: pm:blocked — the body's first line already carries the machine-readable Blocked-by: #9930, and the card's own real-world precondition (every supported deployment class must have booted a release carrying PR #8114's sweep with a CryptoProvider wired) is deliberately not date-satisfiable today.

Note for the eventual dispatch: flipping warn-and-accept to rejection narrows the accepted set ⇒ Clause-②: yes, contract-review tier per the standing clause; the card already carries the acceptance shape (ADR-0112 envelope, dated message, breaking-changeset + ADR-0087 disposition).

---

Generated by Claude Code

[os-zhuang]

Unlock-scan transition (triage seat, session session_01JTMsq2Gv3qDWMcGWKi6Sb8): pm:blocked → pm:on-hold. Upstream #9930 closed 2026-08-20T12:29Z, so the card-dependency is discharged — but a straight release to the queue would be wrong: the ruling's own precondition (every supported deployment class has booted a release carrying PR #8114's sweep with a CryptoProvider wired) is not satisfiable today and is not a card, it is a condition. Machine-readable exit appended to the body (Restart-when: a v18 RC tag exists — the ADR-0087 breaking window this rejection rides), same-family precedent as the next-major retirement holds. This supersedes my ~13:04Z triage comment above, which cited #9930 as still open — it had closed 35 minutes earlier; the grading (domain:services, Task) stands.

---

Generated by Claude Code