feat: fatal main-thread hang detection (#56)

* feat: add fatal main-thread hang detection

Add opt-in detection and reporting of fatal main-thread hangs on iOS,
tvOS, and macOS. A new BugSplatHangTracker class runs a low-QoS
watchdog thread that dispatches a "ping" block to the main queue every
threshold/5 seconds (clamped to at least 100ms). The block, when
serviced, resets an atomic counter; if the counter accumulates enough
unanswered pings to cover `hangDetectionThreshold` seconds, the main
thread is considered hung. When the main thread later services a ping,
a recovery callback fires so the persisted report can be discarded -
only fatal hangs survive to the next launch.

BugSplat persists the report as a synthetic PLCrashReport-style live
report (marking the main thread as crashed via its captured Mach port)
in the crashes directory with bugsplat-hang-* attributes and a per-
launch UUID for correlation with any crash from the same launch. Reuses
the existing next-launch scanner and upload pipeline.

Public API on BugSplat:

* `enableHangDetection` (BOOL, default NO) - opt in before -start
* `hangDetectionThreshold` (NSTimeInterval, default 2.0) - tune the
  unresponsive duration that counts as a hang; clamped to >= 0.1s

Detection is suppressed when a debugger is attached or the app is
inactive (iOS/tvOS background). No-op inside app extensions. -start
must be invoked on the main thread when hang detection is enabled so
the main thread's Mach port can be captured.

Tests cover the watchdog state machine (detection, throttle, recovery,
suspension guard) deterministically via injectable clock and dispatch
blocks, and the BugSplat-side persistence (file layout, metadata,
recovery cleanup).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(samples): demonstrate hang detection in example apps

Wire enableHangDetection into each example app and add a "Simulate Hang"
button that blocks the main thread forever (sleep loop with observable
side effects so the C++ forward-progress rule can't elide it). On the
next launch, a fatal-hang report uploads automatically.

Apps updated: SwiftUI, UIKit-Swift, UIKit-ObjC, macOS-UIKit-ObjC, and
the macOS C++ command-line tool. The CLI tool's loop alternates between
mainObjCRunLoop pumping and getline; the recovery callback discards any
hang report queued during idle prompt waits.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(hang-detector): address Copilot review feedback

* Gate ping dispatch on an outstanding-ping flag so a long hang doesn't
  accumulate an unbounded backlog of ping blocks on the main queue
  (they would all flush at once when main resumed).
* Use millisecond precision for hang report filenames so a same-second
  hang -> recover -> hang cycle can't overwrite a previous report.
* Drop unused imports (pthread, mach, UIKit) left over from the
  CFRunLoopObserver design and add an explicit <math.h> for ceil().
* Sample apps' "Simulate Hang" buttons sleep inside their loops
  instead of busy-spinning at 100% CPU - the main thread is still
  blocked, which is what the demo needs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bobbyg603

BugSplat+Testing.h

@@ -11,18 +11,20 @@
 
 #import "BugSplatTestSupport.h"
 #import "BugSplatUploadService.h"
+#import "BugSplatHangTracker.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 /**
  * Class extension to expose private methods for testing.
  * These methods are implemented in the main BugSplat class.
  */
-@interface BugSplat ()
+@interface BugSplat () <BugSplatHangTrackerDelegate>
 
 - (BOOL)shouldSendCrashSilently:(NSDictionary *)metadata;
 - (NSString *)resolvedApplicationName;
 - (NSString *)resolvedApplicationVersion;
+- (nullable NSString *)crashesDirectoryPath;
 
 @end
 
@@ -83,6 +85,22 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)setDebuggerAttachedOverride:(nullable NSNumber *)value;
 
+#pragma mark - Hang Detection Testing
+
+/**
+ * Create the internal plumbing (serial queue, launch id) that `-start` would
+ * normally set up for hang detection. Lets tests exercise the hang delegate
+ * methods without starting the real tracker or enabling the crash reporter.
+ */
+- (void)setupHangInfrastructureForTesting;
+
+/// Serial queue that hang delegate callbacks dispatch onto; `dispatch_sync` on
+/// this queue to wait for pending hang work to drain.
+- (nullable dispatch_queue_t)hangQueueForTesting;
+
+/// The basename of the hang report most recently persisted by the hang delegate.
+- (nullable NSString *)currentHangFilename;
+
 @end
 
 NS_ASSUME_NONNULL_END

BugSplat.h

@@ -165,6 +165,49 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, assign) BOOL autoSubmitCrashReport;
 
+/**
+ * Enable detection and reporting of fatal main-thread hangs.
+ *
+ * When set to YES before `-start` is invoked, BugSplat monitors the main runloop for
+ * prolonged unresponsive periods while the app is active in the foreground. If a hang
+ * is detected and the app is subsequently terminated without the main thread recovering
+ * (launch/resume watchdog kills, user force-quit), a hang report is uploaded on the next
+ * launch using the same pipeline as crash reports.
+ *
+ * If the main thread resumes after a hang is detected, the persisted report is discarded -
+ * non-fatal hangs are not reported in this version.
+ *
+ * Hang reports carry the exception name `App Hang (Fatal)` and include attributes prefixed
+ * with `bugsplat-hang-` (duration, detection time, app state, launch id) that can be used
+ * to correlate with crashes from the same launch.
+ *
+ * Detection is suppressed when a debugger is attached or the app is not active. As a
+ * consequence, hangs that begin while the app is in the background (including those
+ * terminated by background-task expiration) are not reported.
+ *
+ * This property is a no-op inside app extensions.
+ *
+ * When this property is YES, `-start` must be invoked on the main thread - the
+ * main thread's Mach port is captured there so the hang report identifies the
+ * correct thread. Debug builds assert; Release builds will silently capture the
+ * wrong thread.
+ *
+ * Default: NO
+ */
+@property (nonatomic, assign) BOOL enableHangDetection;
+
+/**
+ * Threshold in seconds for declaring the main thread hung when `enableHangDetection` is YES.
+ *
+ * Must be set before `-start` is invoked. Values below 0.1 are clamped to 0.1 by the
+ * underlying tracker. Typical production values are 1.0-5.0 seconds; choose a value above
+ * any work the app may legitimately do on the main thread (image decoding, JSON parsing,
+ * etc.) to avoid false positives.
+ *
+ * Default: 2.0
+ */
+@property (nonatomic, assign) NSTimeInterval hangDetectionThreshold;
+
 /**
  * Add an attribute and value to a dictionary of attributes that will potentially be included in a crash report.
  * If the attribute is an invalid XML entity name, or the attribute+value pair cannot be set,