Crash reports: replayable, bounded, local, reachable by agents (#384)

Every panic (in a command, in the kernel, anywhere else) and every unclean
exit (abort, stack overflow, kill) leaves a report in a local crash folder:
message, file:line, a trimmed backtrace, version, commit, system and renderer,
the command and recent commands, and when possible the design and replay.json
that reproduce it (solvecraft-cli crashes replay <id>).

- Cost: nothing until the app installs the hook (tests, CLI and web never
  do); then one small journal line per top-level command of the design on
  screen, taken back with a truncate when the command changed nothing.
- Unclean exits: each run holds a lock on its journal; a journal nobody holds
  at the next start belongs to an app that died. Autosaves restart the
  journal from the autosaved design.
- Bounded: a crash's signature (place + message, numbers ignored) is counted,
  not rewritten; at most 5 new reports per run, 20 reports, 50 MB, 90 days;
  recovered kernel panics are pruned first.
- Agents: diagnostics.crash_reports / crash_report / crash_reports.clear
  commands, the MCP crash_reports tool, solvecraft-cli crashes, solvecraft
  --crash-log; diagnostics.crash_test (with SOLVECRAFT_CRASH_TEST) checks it.
- People: the Crash Reports window opens after a crash (Help > Crash
  Reports…) with a reviewed issue draft per report; nothing is sent.
- Release builds keep line tables for file:line in backtraces.

Tests: child processes that really panic in a command, in the kernel, on a
thread, and abort; dedup counts, limits, hostile folders, journal parsing,
the UI window and draft, the MCP tool. docs/crash-reports.md.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: bherbruck <brennen.herbruck@gmail.com>

crates/engine/src/crash_tests.rs

@@ -0,0 +1,289 @@
+use super::*;
+use crate::Session;
+
+fn fresh_dir(name: &str) -> PathBuf {
+    let d = std::env::temp_dir().join(format!("solvecraft-crash-test-{name}-{}", std::process::id()));
+    let _ = fs::remove_dir_all(&d);
+    d
+}
+
+fn build() -> Build {
+    Build { version: "9.9.9", commit: "abc1234", built: "2026-10-12" }
+}
+
+/// The child half of the process tests: does nothing unless a parent asks, then installs the
+/// hook and crashes the way `SOLVECRAFT_CRASH_CHILD` says.
+#[test]
+fn child() {
+    let (Some(dir), Some(mode)) = (std::env::var_os("SOLVECRAFT_CRASH_CHILD_DIR"), std::env::var("SOLVECRAFT_CRASH_CHILD").ok()) else {
+        return;
+    };
+    let fresh = install(PathBuf::from(dir), build());
+    println!("FRESH {}", serde_json::to_string(&fresh).unwrap());
+    set_environment("Renderer: test");
+    let mut s = Session { crash_journal: true, ..Default::default() };
+    s.execute("solid.box", &json!({"length": 10, "width": 20, "height": 30})).unwrap();
+    // Commands that only read are not kept.
+    for _ in 0..50 {
+        s.execute("document.inspect", &json!({})).unwrap();
+    }
+    match mode.as_str() {
+        "command" => {
+            for _ in 0..3 {
+                let r = s.execute("diagnostics.crash_test", &json!({"mode": "panic"}));
+                assert!(matches!(r, Err(crate::EngineError::Internal(..))), "{r:?}");
+            }
+            assert_eq!(s.doc.features.len(), 1, "the design is unchanged");
+        }
+        "kernel" => {
+            assert!(s.execute("diagnostics.crash_test", &json!({"mode": "kernel"})).is_err());
+        }
+        "thread" => {
+            let r = std::thread::Builder::new()
+                .name("worker".into())
+                .spawn(|| std::panic::panic_any(String::from("worker thread 42 failed")))
+                .unwrap()
+                .join();
+            assert!(r.is_err());
+        }
+        "abort" => {
+            let _ = s.execute("diagnostics.crash_test", &json!({"mode": "abort"}));
+        }
+        _ => {}
+    }
+    end_session();
+}
+
+/// Run [`child`] in a new process; returns its stdout and whether it succeeded.
+fn run_child(dir: &Path, mode: &str) -> (String, bool) {
+    let out = std::process::Command::new(std::env::current_exe().unwrap())
+        .args(["--exact", "crash::tests::child", "--test-threads=1", "--nocapture"])
+        .env("SOLVECRAFT_CRASH_CHILD_DIR", dir)
+        .env("SOLVECRAFT_CRASH_CHILD", mode)
+        .env("SOLVECRAFT_CRASH_TEST", "1")
+        .env("RUST_BACKTRACE", "0")
+        .output()
+        .unwrap();
+    (String::from_utf8_lossy(&out.stdout).into_owned(), out.status.success())
+}
+
+fn only_report(dir: &Path) -> (Summary, Value) {
+    let all = list(dir);
+    assert_eq!(all.len(), 1, "{all:?}");
+    let s = all.into_iter().next().unwrap();
+    let v = read(dir, &s.id).unwrap();
+    (s, v)
+}
+
+#[test]
+fn a_command_panic_is_reported_once_with_the_design_and_the_command() {
+    let d = fresh_dir("command");
+    let (_, ok) = run_child(&d, "command");
+    assert!(ok, "the panics were caught");
+    let (s, v) = only_report(&d);
+    assert_eq!(s.kind, "command_panic");
+    assert_eq!(s.count, 3, "repeats are counted, not written again");
+    assert_eq!(s.command.as_deref(), Some("diagnostics.crash_test"));
+    assert!(s.replayable);
+    assert_eq!(v["format"], FORMAT);
+    assert_eq!(v["app"]["version"], "9.9.9");
+    assert_eq!(v["app"]["commit"], "abc1234");
+    assert_eq!(v["system"]["environment"], "Renderer: test");
+    assert!(v["message"].as_str().unwrap().contains("an internal error in a command"), "{v}");
+    assert!(v["location"].as_str().unwrap().contains("diagnostics.rs"), "{v}");
+    let bt = v["backtrace"].as_array().unwrap();
+    assert!(bt.iter().any(|f| f.as_str().unwrap().contains("crash_test")), "{bt:?}");
+    assert!(!bt.iter().any(|f| f.as_str().unwrap().contains("crash::hook")), "the hook's own frames are dropped: {bt:?}");
+    assert_eq!(v["recent_commands"][0]["command"], "solid.box");
+    // The design from before the command, and the command: together they reproduce the crash.
+    let design = solvecraft_io::read_design(&fs::read(v["design_path"].as_str().unwrap()).unwrap()).unwrap();
+    assert_eq!(design.features.len(), 1);
+    let replay: Value = serde_json::from_slice(&fs::read(v["replay_path"].as_str().unwrap()).unwrap()).unwrap();
+    assert_eq!(replay["commands"], json!([{"command": "diagnostics.crash_test", "params": {"mode": "panic"}}]));
+    assert!(fs::read_dir(d.join("sessions")).unwrap().next().is_none(), "a clean exit leaves no journal");
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn a_kernel_panic_is_reported_as_recovered() {
+    let d = fresh_dir("kernel");
+    let (_, ok) = run_child(&d, "kernel");
+    assert!(ok);
+    let (s, v) = only_report(&d);
+    assert_eq!(s.kind, "kernel_panic_recovered");
+    assert!(s.replayable);
+    assert!(v["message"].as_str().unwrap().contains("in the kernel"), "{v}");
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn a_panic_outside_commands_is_reported() {
+    let d = fresh_dir("thread");
+    let (_, ok) = run_child(&d, "thread");
+    assert!(ok);
+    let (s, v) = only_report(&d);
+    assert_eq!(s.kind, "panic");
+    assert_eq!(v["thread"], "worker");
+    assert_eq!(v["message"], "worker thread 42 failed");
+    // What the journal knew: a new design and the box.
+    assert_eq!(v["base"], "new");
+    assert_eq!(v["recent_commands"][0]["command"], "solid.box");
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn an_abort_is_reported_at_the_next_start_with_a_replay() {
+    let d = fresh_dir("abort");
+    let (_, ok) = run_child(&d, "abort");
+    assert!(!ok, "the child aborted");
+    assert!(list(&d).is_empty(), "no hook sees an abort");
+    // The next start finds the journal nobody holds and tells about it.
+    let (out, ok) = run_child(&d, "none");
+    assert!(ok);
+    let fresh: Vec<Value> = out.lines().find_map(|l| l.split_once("FRESH ").map(|x| x.1)).and_then(|j| serde_json::from_str(j).ok()).unwrap();
+    assert_eq!(fresh.len(), 1, "{out}");
+    let (s, v) = only_report(&d);
+    assert_eq!(s.kind, "unclean_exit");
+    assert!(s.message.contains("while running `diagnostics.crash_test`"), "{}", s.message);
+    assert_eq!(v["app"]["version"], "9.9.9");
+    // From a new design: the box, then the command in flight.
+    let replay: Value = serde_json::from_slice(&fs::read(v["replay_path"].as_str().unwrap()).unwrap()).unwrap();
+    let ids: Vec<&str> = replay["commands"].as_array().unwrap().iter().map(|c| c["command"].as_str().unwrap()).collect();
+    assert_eq!(ids, ["solid.box", "diagnostics.crash_test"], "read-only commands are not journaled");
+    assert!(v.get("design_path").is_none());
+    // Told once: the start after that has nothing new.
+    let (out, _) = run_child(&d, "none");
+    assert!(out.contains("FRESH []"), "{out}");
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn a_journal_reads_back_its_base_commands_and_the_one_in_flight() {
+    let d = fresh_dir("journal");
+    fs::create_dir_all(&d).unwrap();
+    let p = d.join("j.jsonl");
+    let lines = [
+        r#"{"start":"2026-10-12T10:00:00Z","version":"1.0"}"#,
+        r#"{"base":"new"}"#,
+        r#"{"run":"solid.box","params":{"length":1}}"#,
+        r#"{"ok":true}"#,
+        r#"{"base":{"autosave":"/tmp/a.solvecraft"}}"#,
+        r#"{"run":"solid.fillet","params":{"radius":1}}"#,
+        r#"{"ok":false,"error":"no edges"}"#,
+        "not json",
+        r#"{"run":"solid.shell","params":{"thickness":1}}"#,
+        r#"{"ok":true}"#,
+        r#"{"run":"solid.extrude","params_omitted":true}"#,
+    ];
+    fs::write(&p, lines.join("\n")).unwrap();
+    let j = read_journal(&p);
+    assert_eq!(j.header["version"], "1.0");
+    assert_eq!(j.base, json!({"autosave": "/tmp/a.solvecraft"}));
+    assert_eq!(j.replay, vec![json!({"command": "solid.shell", "params": {"thickness": 1}})], "failed commands change nothing");
+    assert_eq!(j.recent.len(), 2);
+    assert_eq!(j.recent[0]["error"], "no edges");
+    assert_eq!(j.in_flight.unwrap()["command"], "solid.extrude");
+    assert!(!j.complete, "omitted parameters make the replay incomplete");
+    assert!(!j.reported);
+    let _ = fs::remove_dir_all(&d);
+}
+
+fn fake_report(dir: &Path, secs: u64, sig: u64, kind: &str) -> String {
+    let id = format!("{}-{sig:016x}", stamp(secs));
+    fs::create_dir_all(dir.join(&id)).unwrap();
+    let f = dir.join(&id).join("report.json");
+    fs::write(&f, json!({"format": FORMAT, "id": id, "kind": kind, "message": "m", "count": 1, "first_seen": utc(secs)}).to_string()).unwrap();
+    let t = std::time::UNIX_EPOCH + std::time::Duration::from_secs(secs);
+    File::options().write(true).open(&f).unwrap().set_modified(t).unwrap();
+    id
+}
+
+#[test]
+fn reports_stay_within_their_limits() {
+    let d = fresh_dir("limits");
+    let t0 = 1_790_000_000;
+    let old = fake_report(&d, t0 - (MAX_AGE_DAYS + 1) * 86_400, 1, "panic");
+    let recovered = fake_report(&d, t0 - 100, 2, "kernel_panic_recovered");
+    let mut ids = Vec::new();
+    for i in 0..MAX_REPORTS as u64 {
+        ids.push(fake_report(&d, t0 - 50 + i, 100 + i, "panic"));
+    }
+    prune(&d, t0);
+    let left: Vec<String> = list(&d).into_iter().map(|s| s.id).collect();
+    assert_eq!(left.len(), MAX_REPORTS);
+    assert!(!left.contains(&old), "expired");
+    assert!(!left.contains(&recovered), "recovered kernel panics go before real crashes");
+    // One more: the oldest goes.
+    let newest = fake_report(&d, t0 + 10, 999, "panic");
+    prune(&d, t0 + 10);
+    let left: Vec<String> = list(&d).into_iter().map(|s| s.id).collect();
+    assert_eq!(left.len(), MAX_REPORTS);
+    assert_eq!(left.first(), Some(&newest), "newest first");
+    assert!(!left.contains(&ids[0]));
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn hostile_crash_folders_never_panic() {
+    let d = fresh_dir("hostile");
+    fs::create_dir_all(d.join("sessions")).unwrap();
+    let good = fake_report(&d, 1_790_000_000, 7, "panic");
+    // Junk: a report that is not JSON, one that is an array, stray files and folders.
+    let broken = format!("{}-{:016x}", stamp(1_790_000_001), 8u64);
+    fs::create_dir_all(d.join(&broken)).unwrap();
+    fs::write(d.join(&broken).join("report.json"), b"\xff\xfe{{{").unwrap();
+    let array = format!("{}-{:016x}", stamp(1_790_000_002), 9u64);
+    fs::create_dir_all(d.join(&array)).unwrap();
+    fs::write(d.join(&array).join("report.json"), "[1,2]").unwrap();
+    fs::create_dir_all(d.join("..evil")).unwrap();
+    fs::write(d.join("notes.txt"), "x").unwrap();
+    fs::write(d.join("sessions").join("junk.jsonl"), b"\x00\x01garbage\n{\"run\":5}\n{\"ok\":\"yes\"}").unwrap();
+    let all = list(&d);
+    assert_eq!(all.iter().map(|s| s.id.as_str()).collect::<Vec<_>>(), [good.as_str()]);
+    for id in ["", "../..", "..", "a/b", &"x".repeat(500), &broken] {
+        assert!(read(&d, id).is_err(), "{id}");
+        assert_eq!(clear(&d, Some(id)), usize::from(id == broken), "{id}");
+    }
+    let j = read_journal(&d.join("sessions").join("junk.jsonl"));
+    assert!(j.replay.is_empty());
+    assert!(read_journal(&d.join("missing.jsonl")).replay.is_empty());
+    for (loc, msg) in [("", ""), ("x", &"é".repeat(5000))] {
+        let _ = signature(loc, msg);
+        let _ = limited(msg, 7);
+    }
+    assert!(frames("garbage\n  at nothing\n 99999999999999999999: x").len() <= MAX_FRAMES);
+    let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn signatures_ignore_numbers_but_not_places() {
+    assert_eq!(signature("a.rs:1", "face 12 of 40"), signature("a.rs:1", "face 7 of 3"));
+    assert_ne!(signature("a.rs:1", "face 12"), signature("a.rs:2", "face 12"));
+    assert_ne!(signature("a.rs:1", "edge"), signature("a.rs:1", "face"));
+}
+
+#[test]
+fn dates_are_formatted_in_utc() {
+    assert_eq!(utc(0), "1970-01-01T00:00:00Z");
+    assert_eq!(utc(951_782_400), "2000-02-29T00:00:00Z");
+    assert_eq!(utc(1_791_656_982), "2026-10-10T18:29:42Z");
+    assert_eq!(stamp(1_791_656_982), "20261010-182942");
+}
+
+#[test]
+fn backtraces_lose_the_panic_machinery_and_the_home_folder() {
+    let home = std::env::var("HOME").unwrap_or_else(|_| "/home/u".into());
+    let bt = format!(
+        "   0: std::backtrace::Backtrace::force_capture\n             at /rustc/abc123/library/std/src/backtrace.rs:312:13\n   1: hook\n   1: {{closure#3}}\n   1: <alloc::boxed::Box<F,A> as core::ops::function::Fn<Args>>::call\n   2: std::panicking::rust_panic_with_hook\n   3: core::panicking::panic_fmt\n   4: solvecraft_kernel::fillet::blend\n             at {home}/src/kernel/fillet.rs:10:5\n   5: do_call<F>\n             at /rustc/abc/library/std/src/panicking.rs:1:1\n   5: std::sys::backtrace::__rust_begin_short_backtrace\n   6: main"
+    );
+    assert_eq!(frames(&bt), ["solvecraft_kernel::fillet::blend (~/src/kernel/fillet.rs:10:5)"]);
+}
+
+#[test]
+fn without_install_nothing_is_recorded() {
+    // Tests, the CLI and the web build never install the hook: commands cost nothing extra.
+    let mut s = Session { crash_journal: true, ..Default::default() };
+    s.execute("solid.box", &json!({"length": 1, "width": 1, "height": 1})).unwrap();
+    assert!(!enabled());
+    assert!(PENDING.with(|p| p.borrow().is_empty()));
+}