what

The screenpipe CLI/engine binary had no panic hook. Integrators who embed it as a child process (for example inside an Electron wrapper) only saw an exit code when it died, never why. The last-panic.log + Sentry-flush machinery existed only in the Tauri desktop app (apps/screenpipe-app-tauri/src-tauri/src/main.rs).

This ports it to the engine binary, installed on the Record (long-running server) path only. Subcommands return earlier, so they are unaffected.

how it behaves on a panic

flowchart TD
    A["panic on any thread"] --> B{"tokio shutdown-time noise?"}
    B -- yes --> Z["suppress, stderr only"]
    B -- no --> C["capture payload + location + backtrace"]
    C --> D["append to last-panic.log in the resolved data dir (fsync); rotated to .prev on startup"]
    C --> E["print PANIC to stderr"]
    C --> F["Sentry capture_message Fatal + flush 2s (no-op if telemetry off)"]
    D --> G["embedding parent reads last-panic.log after the child exits"]

what is covered

• Rust panics, on the main thread and background threads. A panic on a worker thread that previously killed only that task, leaving the process degraded and silent, now leaves a record.
• Not covered: native crashes (DLL access violation / SIGSEGV), Windows Defender kills, and OOM. Those are not Rust panics, so the hook cannot see them. They need exit-code / signal mapping in the parent and/or a native crash handler (follow-up).

does it conflict with the desktop app?

No. The desktop app runs its engine in-process (ServerCore::start) and has its own panic hook; this hook only runs when the screenpipe binary is executed directly, so they are different processes. The only shared resource would be the last-panic.log file, so the hook writes to the resolved data dir (honors --data-dir) rather than always ~/.screenpipe. An embedder running with its own --data-dir therefore keeps its crash log next to its own screenpipe.log and never touches the app's file. (The app does not read last-panic.log on startup, so even a shared dir would not cause misattribution, only rotation churn.)

what about the SDK?

Out of scope here, on purpose. @screenpipe/sdk is an in-process napi addon over the screenpipe-recorder crate; it never runs this binary's main(), so it gets nothing from this hook and is also not destabilized by it. A library should not install a global std::panic::set_hook; crash handling for the SDK belongs at the napi boundary (translate a Rust panic into a JS error the host handles) and is a separate change in that crate.

attribution

No new env var. The crash record reuses the existing TelemetryContext embedder attribution (SCREENPIPE_EMBEDDER / SCREENPIPE_HOST_APP / SCREENPIPE_CUSTOMER_ID / SCREENPIPE_DEPLOYMENT_ID), so a local crash record is identifiable even with telemetry off. When telemetry is on, the Sentry scope is already tagged with the same context (see the configure_scope block just above the hook), so panic events inherit it.

sample last-panic.log

[2026-06-05 14:30:01.482] PANIC on thread 'tokio-runtime-worker' at crates/screenpipe-engine/src/foo.rs:42:13: called `Option::unwrap()` on a `None` value
screenpipe_customer_id=acme screenpipe_embedder=acme-desktop

Backtrace:
   0: ...

(The attribution line is omitted when no SCREENPIPE_* context vars are set.)

notes / follow-ups

• Written regardless of telemetry, so analytics-disabled deployments still get a local crash record. For those it is the only crash signal that never leaves the machine.
• The CLI Sentry sample_rate is 0.1, so last-panic.log is the reliable record while the Sentry copy is best-effort. If we want guaranteed panic delivery to Sentry, bump the rate or special-case fatal events.

test plan

• cargo check -p screenpipe-engine --bin screenpipe compiles, no new warnings
• cargo test -p screenpipe-engine --lib crash_log passes (4 tests: append, create-missing-dir, rotate, rotate-no-op). The crash_log helpers take the dir as an argument, so they are agnostic to the data-dir change.
• rustfmt --check clean on the changed files

🤖 Generated with Claude Code