fix(web): portal the natal board peek without effect setState

Quality gate lint failed on setHeaderSlot inside useLayoutEffect, so staging never published. Pass the header mount node from a callback ref instead.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/BUG_HISTORY.md

@@ -5099,6 +5099,22 @@
 - 复发自：BUG-204（报告页 chunk 偏斜已修，首页引导层仍会把同一失败画成永久 loading）
 - 修复版本：50e1a4ac
 
+## BUG-339 | staging quality gate 因盘面入口 effect 同步 setState 失败
+
+- 状态：resolved
+- 首次发现：2026-08-21
+- 最近更新：2026-08-21
+- 影响面：Gitea `backend-quality-gate` `validate`、`rectification-agentic-chat` 窄屏盘面入口 portal
+- 用户现象：向 `staging` 推送后 quality gate 失败，镜像未发布，站点仍停在上一版。日志是 `react-hooks/set-state-in-effect`。
+- 触发条件：`npm run lint --prefix frontend`。自 `8b8e5214` 起，gate run 2019/2020/2021 均因此失败。
+- 根因：窄屏盘面入口用 `useLayoutEffect` 里 `querySelector` 后立刻 `setHeaderSlot`。`eslint-config-next` 禁止在 effect 同步 setState。BUG-335 把入口 portal 到页头时引入该写法。
+- 修复：页头挂载点改用 callback ref，把 DOM 节点作为 `headerSlot` 传给校时会话。仍 `createPortal` 到 `data-rectification-header-slot`，不再在 effect 里查 DOM 或 setState。
+- 验证：`frontend/tests/rectification-agentic-entry.test.ts`；`npm run lint --prefix frontend -- src/components/rectification-agentic-chat.tsx`。
+- 防复发：盘面入口不得在 effect 里 `querySelector` 后同步 setState。源码合同锁定 callback ref 与 `headerSlot` prop，并禁止 chat 内 `setHeaderSlot`。
+- 相关记录：BUG-335、BUG-334
+- 复发自：BUG-335（把入口 portal 到页头时用了 effect 同步 setState）
+- 修复版本：待提交
+
 ## BUG-329 | 生时纠正 Agent 回答在结算后一次性出现，推理中无法停止
 
 - 状态：resolved