1

.hermes/shared-memory/pitfalls.md

@@ -120,6 +120,14 @@
 - 验证：`npm run api-server` 后 `/healthz` 返回 200，相关路由冒烟通过。
 - 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/app.rs`。
 
+## Windows api-server.exe 锁文件与强杀退出码容易混淆
+
+- 现象：`cargo run -p api-server` 或 `npm run api-server` 报 `failed to remove file ... target\debug\api-server.exe`；清理旧进程后，旧终端可能继续打印 `process didn't exit successfully: server-rs\target\debug\api-server.exe (exit code: 0xffffffff)`。
+- 原因：Windows 不能覆盖仍在运行的 exe；通常是上一条 `npm run api-server` 链路仍在运行，进程树为 `npm run api-server -> node scripts/api-server-dev.mjs -> cargo run -> api-server.exe`。`0xffffffff` 常见于排障时用 `Stop-Process -Force` 强制结束旧 `api-server.exe` 后由 Cargo 回显，不一定代表新启动失败。
+- 处理：先按目标路径确认并停止本仓库的旧 `api-server.exe` 及其父级 `cargo/node/cmd` 启动链路，再重新启动；不要同时开多个 `npm run api-server`。
+- 验证：确认没有匹配 `C:\Genarrative\server-rs\target\debug\api-server.exe` 的进程后，`Remove-Item` 能删除旧 exe；随后 `npm run api-server` 启动并访问 `/healthz` 返回 200。
+- 关联：`scripts/api-server-dev.mjs`、`server-rs/crates/api-server/src/main.rs`。
+
 ## Windows debug 长 SSE Future 触发 api-server 断连
 
 - 现象：前端 Vite 代理请求 `/api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 报 `read ECONNRESET`，随后 `api-server.exe` 以 `0xffffffff` 退出，`dev:rust` 回收 SpacetimeDB、Vite 和后台 Vite。