WEBDIENSTE/openswarm
1
0
Fork 0
mirror of https://github.com/openswarm-ai/openswarm.git synced 2026-09-10 03:37:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

[eric] docs: precedences for crash mitigations (silent in both directions, per-platform, every guard not most)

Browse Source
This commit is contained in:
eric
2026-05-31 21:52:38 -07:00
parent f325bc28c3
commit 91d68985de
1 changed files with 3 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
electron/CLAUDE.md
+3
View File
@@ -46,3 +46,6 @@ For any change touching paths, subprocess spawning, IPC, deep links, or the auto
- **Renderer origin (port) must be stable across launches.** `localStorage` is keyed by full origin including port, so `server.listen(0)` (OS-assigned random port) was wiping onboarding state every restart and re-triggering the tour. Pin to a preferred port (currently `4173`), fall back to OS-assigned only if held. Same rule applies to any future renderer-side persisted state.
- **`webSecurity` stays on.** The file:// segfault was fixed by serving over `http://127.0.0.1:<port>`, NOT by disabling web security. Any future "let's just disable CSP" fix is wrong; find the underlying file:// quirk and route around it (loopback HTTP is the canonical workaround).
- **Mitigations must fail silently in BOTH directions.** When adding a workaround for an Electron / Chromium / platform-level crash you can't fix in our code, every option has two failure modes: (a) the mitigation doesn't help, and (b) the mitigation activates incorrectly and breaks something that was working. The latter is far worse than the former because it produces NEW failure modes we have to debug. Pick options that fail-quiet in both directions; reject options that fail-loud when they succeed (e.g. "hide window on sleep" successfully prevents a crash but every sleep-wake cycle now has a confused user).
- **Per-platform scope every workaround.** If the crash signature is OS-specific (e.g. macOS 26 NSEvent, Windows TSF), gate the workaround behind `process.platform === '<os>'`. Don't apply Mac dodges on Windows (or vice versa) "just to be consistent" — that's pure surface-area expansion for zero crash-fix benefit, and risks introducing new platform-specific regressions on the OS that wasn't crashing.
- **Crash watchdogs need EVERY guard, not most of them.** A naive "process died → relaunch" loop kills more sessions than it saves because it fires on intentional Cmd+Q, auto-updater swaps, and startup crash loops. Mandatory guards: (1) platform check, (2) packaged-only check, (3) clean-quit lock written by `before-quit`, (4) updater-in-progress lock, (5) minimum parent uptime (rules out startup crash loops), (6) relaunch frequency cap (e.g. ≤3 relaunches per hour). See `electron/crash-watchdog.js` for the canonical implementation. If you're adding another supervisor process for a different reason, copy this guard pattern verbatim.