合并主分支并修复 Runner GUI owner 重挂

合并最新 master 的 Runner 登记模型与托管 MCP 变更
登记真实事件接收端口和令牌并按 bootId 幂等重放
严格校验 owner 与事件接收端双重确认并保留失败重试
补齐跨 boot、同 boot、失败确认、AppData 隔离和 CLI 无副作用测试
保留双方 pitfalls 条目并同步技术方案与项目记忆

docs/project-memory/shared-memory/pitfalls.md

@@ -4158,3 +4158,18 @@
 - 原因：脚本用 `Buffer.readUInt32BE(0)` 读取文件头，却只比较 `0xfeedfacf` 等正序数值；arm64 常见头字节是 `cf fa ed fe`，读取结果为 `0xcffaedfe`。
 - 处理：文件头白名单同时覆盖 32/64 位与 fat Mach-O 的正序和反字节序合法魔数，并由桌面配置门禁同时反查 staging 脚本和根级产物检查，不能改成只按扩展名或构建退出码判断。
 - 验证：在 macOS 上构建真实 desktop-shell release，运行 `npm run desktop-shell:stage-release-binary`，再由 `npm run check:native-shells` 校验 staged 产物。
+
+## 托管 MCP 新增公开域名时不能只更新网关路由（2026-08-05）
+
+- 现象：`https://dev.genarrative.world/api/external/v1/mcp` 的 manifest、OpenAPI 和 Bearer 鉴权都正常，但鉴权后的 `initialize` 返回 `403 FORBIDDEN`；通过 SSH 隧道访问同一 api-server 的 loopback 地址却可以正常列出 tools/resources。
+- 原因：`rmcp` Streamable HTTP transport 自带 DNS rebinding 防护。公网网关已经接入 dev 域名，但 `external_mcp::service()` 的 `allowed_hosts` / `allowed_origins` 仍只登记正式域名和 localhost，因此请求在 MCP 协议处理前被 transport 拒绝。
+- 处理：新增公开 MCP 环境时，同批登记对应 Host 与 HTTPS Origin；不要通过客户端伪造 `Host`、关闭防护或改走内部 SpacetimeDB MCP 规避。allowlist 变更属于 api-server 发布内容，必须随正常 API release 部署到目标环境。
+- 验证：自动测试使用真实公开 Host/Origin 执行 `initialize`；部署后再从公网域名完成带 Key 的 `initialize`、`tools/list`、`resources/list`、Skill resource 读取和至少一个只读业务 tool 调用。loopback 成功只能证明 MCP 实现和 Key 可用，不能替代公网 Host 验收。
+- 关联：`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+
+## GUI owner 锁不能替代逐 boot 的事件接收端登记（2026-08-05）
+
+- 现象：GUI 首次启动后 manifest 事件转发正常，但 Runner 被替换为新 boot 后只剩 owner 锁和 endpoint 可用，后台更新不再到达 GUI；或者 attach 响应只确认 owner，客户端却误记当前 boot 已完整登记，后续 ensure 不再重试。
+- 原因：把 OS owner 生命周期约束与进程内事件 sink attachment 混成同一状态，或在 `ensure_external_agent_runner` 之外执行一次性 attach；测试若用 actionId 等无关字段代替真实 sink port/token，也无法证明新 boot 重放的是可用接收端。
+- 处理：GUI 按规范化 AppData 私有登记真实 sink port/token，`ensure_external_agent_runner` 的 endpoint 复用和新 Runner 就绪两条成功路径都按 `bootId` 重放。同 boot 成功后幂等，新 boot 必须重挂；RPC、`attached` 或 `eventSinkAttached` 任一失败或缺失都不得记录成功 boot，并允许同 boot 后续重试。不同 AppData 不共享登记，未登记 CLI 不触发 attach；sink token 不进入日志、错误或公共状态。
+- 验证：分别覆盖真实 port/token 跨 boot 原样重放、同 boot 幂等、新 boot 重挂、普通 attach 失败、`eventSinkAttached` 缺失与 false 后同 boot 重试、AppData 隔离和未登记 CLI 零副作用。