feat(inspector): runtime inspector activation via SIGUSR1 + CDP pause during busy execution

src/bun.js.zig

@@ -49,6 +49,8 @@ pub const Run = struct {
                 .smol = ctx.runtime_options.smol,
                 .debugger = ctx.runtime_options.debugger,
                 .dns_result_order = DNSResolver.Order.fromStringOrDie(ctx.runtime_options.dns_result_order),
+                .disable_sigusr1 = ctx.runtime_options.disable_sigusr1,
+                .inspect_port = ctx.runtime_options.inspect_port,
             }),
             .arena = arena,
             .ctx = ctx,
@@ -186,6 +188,8 @@ pub const Run = struct {
                     .debugger = ctx.runtime_options.debugger,
                     .dns_result_order = DNSResolver.Order.fromStringOrDie(ctx.runtime_options.dns_result_order),
                     .is_main_thread = true,
+                    .disable_sigusr1 = ctx.runtime_options.disable_sigusr1,
+                    .inspect_port = ctx.runtime_options.inspect_port,
                 },
             ),
             .arena = arena,

src/bun.js/Debugger.zig

@@ -119,7 +119,6 @@ pub fn create(this: *VirtualMachine, globalObject: *JSGlobalObject) !void {
     log("create", .{});
     jsc.markBinding(@src());
     if (!has_created_debugger) {
-        has_created_debugger = true;
         std.mem.doNotOptimizeAway(&TestReporterAgent.Bun__TestReporterAgentDisable);
         std.mem.doNotOptimizeAway(&LifecycleAgent.Bun__LifecycleAgentDisable);
         std.mem.doNotOptimizeAway(&TestReporterAgent.Bun__TestReporterAgentEnable);
@@ -128,9 +127,13 @@ pub fn create(this: *VirtualMachine, globalObject: *JSGlobalObject) !void {
         debugger.script_execution_context_id = Bun__createJSDebugger(globalObject);
         if (!this.has_started_debugger) {
             this.has_started_debugger = true;
-            var thread = try std.Thread.spawn(.{}, startJSDebuggerThread, .{this});
+            var thread = std.Thread.spawn(.{}, startJSDebuggerThread, .{this}) catch |err| {
+                this.has_started_debugger = false;
+                return err;
+            };
             thread.detach();
         }
+        has_created_debugger = true;
         this.eventLoop().ensureWaker();
 
         if (debugger.wait_for_connection != .off) {

src/bun.js/VirtualMachine.zig

@@ -164,6 +164,9 @@ hot_reload_counter: u32 = 0,
 
 debugger: ?jsc.Debugger = null,
 has_started_debugger: bool = false,
+/// Pre-configured inspector port for runtime activation (via --inspect-port).
+/// Used by RuntimeInspector when SIGUSR1/process._debugProcess activates the inspector.
+inspect_port: ?[]const u8 = null,
 has_terminated: bool = false,
 
 debug_thread_id: if (Environment.allow_assert) std.Thread.Id else void,
@@ -1086,9 +1089,12 @@ pub fn initWithModuleGraph(
     vm.jsc_vm = vm.global.vm();
     uws.Loop.get().internal_loop_data.jsc_vm = vm.jsc_vm;
 
+    vm.inspect_port = opts.inspect_port;
     vm.configureDebugger(opts.debugger);
     vm.body_value_hive_allocator = Body.Value.HiveAllocator.init(bun.typedAllocator(jsc.WebCore.Body.Value));
 
+    configureSigusr1Handler(vm, opts);
+
     return vm;
 }
 
@@ -1115,8 +1121,28 @@ pub const Options = struct {
     /// Worker VMs are always destroyed on exit, regardless of this setting. Setting this to
     /// true may expose bugs that would otherwise only occur using Workers.
     destruct_main_thread_on_exit: bool = false,
+    /// Disable SIGUSR1 handler for runtime debugger activation (matches Node.js).
+    disable_sigusr1: bool = false,
+    /// Pre-configured inspector port for runtime activation (--inspect-port).
+    inspect_port: ?[]const u8 = null,
 };
 
+/// Configure SIGUSR1 handling for runtime debugger activation (main thread only).
+fn configureSigusr1Handler(vm: *const VirtualMachine, opts: Options) void {
+    if (!opts.is_main_thread) return;
+
+    if (opts.disable_sigusr1) {
+        // User requested --disable-sigusr1, set SIGUSR1 to default action (terminate)
+        jsc.EventLoop.RuntimeInspector.setDefaultSigusr1Action();
+    } else if (vm.debugger != null) {
+        // Debugger already enabled via CLI flags, ignore SIGUSR1
+        jsc.EventLoop.RuntimeInspector.ignoreSigusr1();
+    } else {
+        // Install RuntimeInspector signal handler for runtime activation
+        jsc.EventLoop.RuntimeInspector.installIfNotAlready();
+    }
+}
+
 pub var is_smol_mode = false;
 
 pub fn init(opts: Options) !*VirtualMachine {
@@ -1213,9 +1239,12 @@ pub fn init(opts: Options) !*VirtualMachine {
     if (opts.smol)
         is_smol_mode = opts.smol;
 
+    vm.inspect_port = opts.inspect_port;
     vm.configureDebugger(opts.debugger);
     vm.body_value_hive_allocator = Body.Value.HiveAllocator.init(bun.typedAllocator(jsc.WebCore.Body.Value));
 
+    configureSigusr1Handler(vm, opts);
+
     return vm;
 }
 
@@ -1262,8 +1291,15 @@ fn configureDebugger(this: *VirtualMachine, cli_flag: bun.cli.Command.Debugger)
             }
         },
         .enable => {
+            // If --inspect/--inspect-brk/--inspect-wait is used without an explicit port,
+            // use --inspect-port if provided.
+            const path_or_port = if (cli_flag.enable.path_or_port.len == 0)
+                this.inspect_port orelse cli_flag.enable.path_or_port
+            else
+                cli_flag.enable.path_or_port;
+
             this.debugger = .{
-                .path_or_port = cli_flag.enable.path_or_port,
+                .path_or_port = path_or_port,
                 .from_environment_variable = unix,
                 .wait_for_connection = if (cli_flag.enable.wait_for_connection) .forever else wait_for_connection,
                 .set_breakpoint_on_first_line = set_breakpoint_on_first_line or cli_flag.enable.set_breakpoint_on_first_line,
@@ -1463,9 +1499,12 @@ pub fn initBake(opts: Options) anyerror!*VirtualMachine {
     if (opts.smol)
         is_smol_mode = opts.smol;
 
+    vm.inspect_port = opts.inspect_port;
     vm.configureDebugger(opts.debugger);
     vm.body_value_hive_allocator = Body.Value.HiveAllocator.init(bun.typedAllocator(jsc.WebCore.Body.Value));
 
+    configureSigusr1Handler(vm, opts);
+
     return vm;
 }