app: a crash report says whose code crashed

[foxnne]

Part of plans/RESTART_AND_CRASHES_PLAN.md, step 3 (crash reports), first PR.

What changes

When fizzy crashes, it says whose code crashed. The report names fizzy itself or the plugin, with versions, every loaded module and each stack frame as a module plus an offset. It goes to stderr and to <config>/crashes/<launch ms>-<pid>.txt. A plugin crash in a ReleaseFast build, from a sandbox run:

fizzy crashed in crashy 0.3.1: Segmentation fault at address 0x10

fizzy 0.2.0, sdk 0.2.22 (1bf417f650c67637), macos aarch64 ReleaseFast

modules:
  0 fizzy 0.2.0 0x1028ec000 0xe353cc bc2c449a69303c4fa630cc912ef818f2
  1 workbench 0.1.1 0x1204dc000 0x27e41c 37365a5baeef32629cd6ff1518dde68e
  …
  5 crashy 0.3.1 0x125898000 0x107798 f1055092556d30e1aed6ec438d739214
frames:
  crashy+0x531bc
  crashy+0x1d12b
  fizzy+0x5a6b9f
  …
  0x180f3bdff dyld

Before this, a release build had no fault handler at all: a crash printed nothing.

What reaches it (app/crash/crash.zig):

• A panic in fizzy: the root's panic handler is now FullPanic(crash.panic).
• A fault anywhere in the process: std's segfault handler, switched on in every build mode (enable_segfault_handler), routed through root.debug.handleSegfault. Covers SIGSEGV/BUS/ILL/FPE and Windows access violations.
• An abort or trap anywhere (POSIX): a SIGABRT/SIGTRAP handler. A plugin's panic lands here: the dylib has its own std, which prints the message and calls abort().

After the report, each one hands on to what ran before: std's handler, which still prints the symbolized trace (the executable isn't stripped), or the signal's default action. Only one report is written per run, so fizzy's own panic doesn't also report the abort it ends in.

The module table: a fixed table of 64 slots.

• The executable (and the plugins linked into it) is entered first thing in main.
• Each plugin dylib is entered in PluginLoader.register before its register runs, and removed in unloadPlugin before dlclose.
• Each entry's range and build id are read from the mapped headers at load time (app/crash/image.zig): the Mach-O LC_UUID, the ELF NT_GNU_BUILD_ID note, or the PE CodeView GUID+age. A crash only compares addresses.
• An address in no known module (system libraries) is named with dladdr.

Build ids on ELF: Zig's linker writes a build id only when asked. The executable and plugins built for ELF now set build_id = .fast (build/exe.zig, sdk/plugin_sdk.zig).

Writing allocates nothing: the file is named once the config folder is known (crash.writeTo, in Editor.init), and a crash writes it with open/write (CreateFileW/WriteFile on Windows) from a static buffer. A crash before that point reports to stderr only. A run that doesn't crash leaves no file.

Cost: none per frame. The handlers are installed once, and each plugin load does one table write. std already attaches the per-thread alternate signal stack whenever signal_stack_size is set, which is the default, so turning the handler on in release builds adds nothing there.

crash is a std-only module of its own (build/sdk.zig's crashModule), so the plugin-loader test, which is rooted at PluginLoader.zig, can reach it. The app re-exports it as app.crash.

SDK impact

• None
• Core-only or additive: reaches plugins at the next SDK release. plugin_sdk.zig gives ELF plugins a build id; no fingerprint move (test-sdk-version passes).
• Fingerprint moved
• SDK release

Verified

• macOS (arm64), in a sandbox profile with a throwaway plugin that crashes in its register on request:
  • Plugin segfault (Debug and ReleaseFast): reported as crashed in crashy 0.3.1. Each crashy+0x… offset matches std's symbolized trace (crashy+0x1b9404 = 0x12ba11404 in deep).
  • Plugin panic: the plugin's std prints the message and aborts, and the report says crashed in crashy 0.3.1: Abort, with frames from libsystem_c into crashy.
  • fizzy's own panic: the first sandbox run panicked in this PR's own code (an aliasing bufPrint in writeTo, fixed). The report named fizzy with its frames, and std's trace followed.
  • kill -SEGV while idle (ReleaseFast): the report shows system frames (kernel, CoreFoundation, HIToolbox, AppKit) named by image, then fizzy's.
  • kill -TERM: a normal exit, no report file.
• Gates: zig build; zig build test (85/85 steps, 525/526 tests, 1 skipped), including the new fizzy-crash-tests (report text, image lookup, build-id note parsing); test-integration (44/44 steps, 359/359); check-web; test-sdk-version. scripts/check-examples.sh built example-plugin against this tree; its example-app half fails locally on macOS (the script writes an absolute temp path into the zon, which Zig rejects), unrelated to this change, so that half is CI's.
• Linux: CI. The crash tests cross-compile for x86_64-linux-gnu, handlers included (refAllDecls).
• Windows: CI. The crash tests cross-compile for x86_64-windows-gnu.
• Web: check-web; nothing is installed there (crash.supported is false).

Follow-ups

• A plugin's panic message in its report: the dylib entry the build helper generates declares a panic that forwards to the host's crash.panic through a symbol the executable exports. This also covers Windows, where a plugin's panic ends in RtlExitUserProcess(3), which no handler sees, so today it writes no report.
• The report string: about 150 bytes, frames as module index plus VLQ offset, paste-able (plan step 3).
• On the next launch: say fizzy crashed and whose code it was; "Report" opens a prefilled issue on that plugin's repo; safe mode offers to leave that plugin off.
• Symbols: release builds upload their debug info by build id (fizzy's release and plugin-build-action), and the next launch resolves the frames locally.
• A ring of the last log lines in the report, and the risky features in use (floats, glass, a live tape).
• Frame pointers in release builds: measure the cost before deciding. On aarch64 macOS the ABI keeps them anyway, which is what the ReleaseFast run above walked.

🤖 Generated with Claude Code