Desktop hangs leave no record: a stall watchdog with sample, local crash dumps, and a quit deadline

[josephv123]

Note

Claude Opus 5.5 in Claude Code, writing on behalf of @josephv123. Following up on #21301, as suggested there.

Problem

On 2026-10-18 the desktop main process on Joseph's Mac stopped making progress. It was running Nightly 0.1.1-nightly.20261018.3315 on macOS 27.0.1 (M5, 16 GB), under critical memory pressure: 28 GB of swap while 12 agents ran test suites.

• 13:49: last main-process span. 13:59: WindowServer ping timeout.
• 14:53: logout waits on T3 Code. 14:55: force-quit twice, then killed with signal 9.
• No crash report, hang report or dump. The desktop logs show only a gap.

#21301 has the details. It was closed because there is no stack, and so no root cause. The candidates (V8 heap thrashing through swap, a blocking native call on the main thread, a starved libuv pool) all leave the same record: nothing. A stack from the next hang would tell them apart.

Proposals

The four are independent.

1. Main-thread watchdog, with sample on macOS. The main thread writes a heartbeat to shared memory every second, and a worker thread checks it. After 10 s without one, the worker:

   • appends a record to main-thread-stalls.ndjson in the log directory;
   • on macOS, for the first stall in a run, starts /usr/bin/sample <pid> 5 -mayDie;
   • on Linux, records the main thread's kernel state and wchan.

   It appends a second record with the stall's length when the heartbeat resumes.

   • Captures: where the main thread is stuck, with no user action. On macOS that is native and V8 frames. On Linux it shows whether the thread waits on a lock (S, futex_do_wait), is busy (R), or waits on disk or swap (D). If the libuv pool is starved instead, the heartbeat continues and no stall is recorded, even though spans stop reaching the disk. That rules out a stuck main thread.
   • Limits: the worker costs about 10–14 MB of RSS. It takes one sample per run. Windows gets the record without a stack. Computer sleep and a paused process are not counted. If the whole process stops getting CPU, the worker stops too.
   • Prototype: on macOS 27.0.1 a hardened-runtime node sampled itself. With the main thread blocked in Atomics.wait, all 4,216 samples ended in Builtin_AtomicsWait → FutexEmulation::WaitSync → __psynch_cvwait. With a busy JavaScript loop they were in interpreter and JIT frames. Not yet run inside the packaged app, which is also hardened-runtime signed.

2. unresponsive / responsive logging on app windows.

   • Captures: renderer hangs and their length, in the trace.
   • Limits: Electron emits these events from the main process. Nothing is logged while the main process itself is stuck, as in [Bug]: A hung desktop main process leaves no record and blocks macOS logout until force-quit #21301.

3. Local-only crashReporter. crashReporter.start({ uploadToServer: false }) keeps Crashpad minidumps in app.getPath("crashDumps") and uploads nothing.

   • Captures: native crashes and V8 out-of-memory aborts in the main and renderer processes, such as [Bug]: Linux/Wayland desktop main process aborts with V8 heap OOM (SIGTRAP), no preview/CDP activity #21189 and [Bug]: macOS main process aborts with V8 OOM in JSON.stringify while relaying preview CDP events (SIGTRAP) #20395. It would also show whether [Bug]: Linux/Hyprland desktop exits silently with no crash diagnostics #10911's silent exits are crashes. Today these leave nothing behind.
   • Limits: a hang is not a crash, and force quit sends SIGKILL, so [Bug]: A hung desktop main process leaves no record and blocks macOS logout until force-quit #21301 would still leave no dump. Reading a minidump needs Electron's symbols, and users would attach the files to issues by hand.

4. Quit deadline. After 10 s, the app logs which shutdown step is stuck, still requests the backend stop, and waits 2 s so the trace file keeps the warning. Then it calls app.exit(0).

   • Fixes: quit or logout blocked forever by a shutdown step that never finishes. Today the window-bounds write has no timeout. A backend stop also takes the instance lock before its 5 s timeout starts.

   • Limits: as you pointed out, the deadline runs on the main thread. It only helps when main is alive but a shutdown step never completes, so it would not have fired in [Bug]: A hung desktop main process leaves no record and blocks macOS logout until force-quit #21301. A forced exit skips the remaining finalizers, which is safe for two reasons:

     • The window-bounds file is written to a temp file and renamed, so it is never half-written.
     • A backend whose own stop is stuck notices its launcher is gone within about 2 s through fix(server): desktop backend now exits when its launcher dies #20277's launcher watch. That watch doesn't run on Windows.

     fix(desktop): let lifecycle shutdown finish before exiting #20303 would raise the backend stop timeout to 45 s, and the deadline would have to stay above it.

   • Prototype:

     • Two tests, for a window-bounds flush and a backend stop that never finish, time out on main and pass with the change.
     • A live run with the real lifecycle module and trace sink logged the warning at +10 s, naming the step, and exited at +12.0 s.
     • A healthy shutdown still quits through app.quit() as before.
     • Without the 2 s wait, the warning never reached the trace file.

Prototype

The branch https://github.com/josephv123/t3code/tree/feat/desktop-hang-diagnostics has the quit deadline and the watchdog as two separate commits, with tests. In apps/desktop, vp test run src/app/DesktopLifecycle.test.ts src/telemetry/MainThreadWatchdogWorker.test.ts gives 10 passed. The unresponsive logging and crashReporter are not prototyped.

Question

Which of these would you take as focused PRs? The watchdog is the one that would have given #21301 a stack. Joseph can run any of them on his Mac.

Related: #10911, #21189, #20395, #20329.