[Bug Report] 欢迎弹窗（内测声明）在 settings 写入被拒时把用户永久锁死：无法关闭、只能无限重试"暂时无法保存确认状态，请重试"

[DRAG0NM]

摘要

欢迎弹窗（WelcomeNotice）的确认动作走特权 RPC settings.mutate（ui-onboarding.welcomeNoticeVersion），而 settings.* 系列被信任围栏钉死在 loopback + 同源（PRIVILEGED_METHODS 空信任列表）。一旦浏览器上下文不满足围栏（iframe 嵌入、非 loopback 访问、代理/扩展改写 Origin/Host、sec-fetch-site: cross-site），settings.mutate 返回 403 → acknowledge() 失败 → 弹窗显示"暂时无法保存确认状态，请重试"。而弹窗本身没有任何逃生口：OnboardingModal 把 onClose 设为空函数、headless（无关闭钮）、并把整个应用根 inert。于是用户被永久锁死在弹窗里，只能无限点击"继续"重试同一条必失败的 403 请求——这正是 #737 的现象。

复现步骤

1. 启动 dsh web（默认监听 127.0.0.1:3080）。
2. 用不满足同源围栏的方式打开 UI：嵌入 iframe（如宿主工具面板）、或经端口转发/局域网访问、或浏览器扩展改写请求头（参考 dsh web 打开后所有 /api/* 请求返回 403（transport failure for /api/host.describe / host.pickDirectory: HTTP 403），curl 直连却是 200 #313 的触发面）。
3. 首次进入即弹"内测声明"，点击"继续"。
4. 结果：提示"暂时无法保存确认状态，请重试"持续出现；弹窗无法关闭（无 X、Esc/点遮罩无效、页面其余部分不可交互）；刷新后再次进入仍被锁死。

根因（源码定位，rc.6）

1. dsh-client-ui-settings-models/lib/client.js OnboardingModal（L2102-2135）：
   onClose: ignoreImplicitDismiss（空函数，L2094/2119）、headless: true、
   appRoot.inert = true（L2107）——弹窗无任何关闭途径，且锁死整个应用根。
2. 同文件 WelcomeNotice（L2252-2299）：只有"继续"一个按钮（L2287-2295），
   点击后 acknowledge()；渲染条件（L2267）在 status === "error" 时仍渲染弹窗。
3. 同文件 WelcomeNoticeStore.acknowledge()（L2392-2430）：host 模式下调用
   api.settings.mutate(...)；response.result.ok 为 false 时抛错 → 返回 false
   → state.error 置位（L2423-2427）→ 界面显示 welcomeError
   （"暂时无法保存确认状态，请重试"，L2628）。
4. dsh-client-connection/lib/index.js PRIVILEGED_METHODS（L504-520）：
   settings.mutate 等特权方法用空信任列表二次校验（L538），非
   loopback+同源请求一律 403 "forbidden"——围栏本身按设计工作（dsh web 打开后所有 /api/* 请求返回 403（transport failure for /api/host.describe / host.pickDirectory: HTTP 403），curl 直连却是 200 #313 已实测矩阵）。
5. 死锁组合：persistence = connection.isLoopback ? "host" : "memory"（L2687）在页面
   首次加载时判定；iframe/转发场景下浏览器可能被判为 loopback 走 host 模式，
   但请求携带的 Origin/sec-fetch-site 不满足围栏 → mutate 403 → 弹窗永远
   停留在 error 态。memory 模式的本地确认路径（L2394-2401）只在"非 loopback"
   判定时生效，救不了上述组合。

建议修复

方案 A（推荐）· 确认失败时本地降级 + 后台补写：acknowledge() 失败时不再
阻塞——先在内存/本地标记 acknowledged = true 放行弹窗（该声明是信息性的，
不承载任何安全语义），随后静默重试一次持久化；彻底失败仅提示"稍后可重试"。
一处修改同时解决"锁死"与"无限重试"。

方案 B · 给弹窗加显式逃生口：OnboardingModal 提供"跳过/稍后"按钮（等价
memory 模式确认）；或 welcomeError 状态时允许 Esc/遮罩关闭。

方案 C（诊断）· 暴露真实错误：错误文案直接展示底层原因（如
HTTP 403 (settings 写入仅限本机同源)），而不是笼统的"暂时无法保存"——用户
至少能知道是环境问题而非"保存失败"。

影响

• 任何在 iframe/转发/代理环境打开 dsh web 的用户（包括把 dsh 嵌进宿主工具
  面板的场景）首次进入即被弹窗永久锁死，UI 完全不可用，刷新无效
• 每次点击"继续"都重发一条注定 403 的 settings.mutate，无限空转
• 与 dsh web 打开后所有 /api/* 请求返回 403（transport failure for /api/host.describe / host.pickDirectory: HTTP 403），curl 直连却是 200 #313/Ask: 端口转发跨host后工作记录显示缺失 #437 同一信任围栏的第三触发面（前两者是 403 全挂/记录缺失，此处是
  交互死锁）

环境

• 源码定位：0.1.0-rc.6（npx 缓存安装包，Node v24.16.0，Windows 11）
• 原报告：[Bug] Welcome notice (内测声明) modal cannot be dismissed: "暂时无法保存确认状态，请重试" persists after clicking Continue #737（0 评论，此前无人分析）

验证材料

• 根因节 5 个源码定位点构成完整链路（弹窗无逃生口 → 确认走特权 RPC →
  围栏 403 → 错误态永久渲染）
• 围栏 403 触发面已有实测矩阵（见 dsh web 打开后所有 /api/* 请求返回 403（transport failure for /api/host.describe / host.pickDirectory: HTTP 403），curl 直连却是 200 #313 的报告）：Origin ≠ Host、
  sec-fetch-site: cross-site、Host 非 loopback 均复现 403
• 逻辑复现：任何满足上述触发面的环境按复现步骤 4 步即可看到锁死

---

First analysis of discussion #737. Happy to open a PR with fix option A.

[meikongyoumo]

补充一个我在 WorkBuddy（CodeBuddy 桌面端）环境里实测到的第二个根因。它和 #860 说的信任围栏 403 是两条独立的路，但症状一样：点「继续」报「暂时无法保存确认状态」，弹窗还关不掉。

现象

同源 loopback 直连（不是 iframe、没有跨源）的时候，settings.mutate 照样失败，不过返回的不是 403，是：

settings-rejected: [safe-delete] 操作失败: ERROR C:\Users\PPY\.dsh\settings.yaml.lock:
Error during a `trash` operation: Unknown { description: "Some operations were aborted" }

根因：环境注入的 safe-delete shim 把 fs.rm 拦了

WorkBuddy 桌面端会给每个 node 子进程注入：

NODE_OPTIONS=--require ".../genie-safe-delete.cjs"

这个 shim 把 fs.rm / fs.unlink 改成了「移到回收站」。这台机器上回收站操作会失败（就是上面那句 "Some operations were aborted"），于是 fs.rm 抛错。

dsh 的 withFileLock（在 @deepseek-ai/dsh-atomic-write 里）会在 finally 里 rm(lockPath, { force: true }) 清理 settings.yaml.lock。于是：

1. writeFileAtomic 其实已经写成功了，settings.yaml 里确实有 welcomeNoticeVersion。
2. 但 finally 里那下 rm(lockPath) 被 shim 打断，抛了错。
3. 异常往上冒，settings.mutate 返回 ok:false（settings-rejected）。
4. 前端 acknowledge() 失败，弹 welcomeError。弹窗又没逃生口，就锁死了。

换句话说，文件明明写进去了，就因为在清理锁文件这一步挂了，整个 mutation 被算成失败。这是 dsh 对锁清理失败处理得太严了。

验证

用 curl 直连同源 loopback 复现，绕开 iframe 围栏：

curl -s -X POST http://127.0.0.1:8080/api/settings.mutate \
  -H "Content-Type: application/json" \
  -d '{"type":"client-request","rpcId":"m1","method":"settings.mutate","payload":{"ns":"ui-onboarding","ops":[{"op":"set","path":["welcomeNoticeVersion"],"value":"2026-08-13.1"}]}}'

返回就是上面那条 settings-rejected，不是 403。而且 ~/.dsh/settings.yaml 的内容其实已经被改掉了。

修复 / 绕过

启动 dsh 前把这个变量清空就行：

# bash
NODE_OPTIONS= dsh web
# PowerShell
$env:NODE_OPTIONS=""; dsh web

清掉之后 settings.mutate 就返回 ok:true 了，~/.dsh 下也不再留 .lock。

给维护者的建议

withFileLock 的 finally 里 rm(lockPath) 失败，不该让整个 mutation 一起失败。到那一步文档已经通过原子写提交了，锁文件没清掉顶多算个 warning，重试或者下次覆盖都行。这么改一下，safe-delete shim 这种「写入成功、清理失败」的情况就一并覆盖了，和方案 A（失败时本地降级）其实是同一个方向。

[DRAG0NM]

感谢 @meikongyoumo 补充的第二个根因（safe-delete shim 拦截 fs.rm 导致锁清理失败 → settings.mutate 返回 settings-rejected）。这与原文的信任围栏 403 是两条独立路径、同一症状，补充得很到位——尤其"写入已成功、仅锁清理失败却整体判失败"这一点，是原子写+锁清理把失败面放得过大的独立问题。感谢完整的环境与复现说明。