Support multi-process debugging: sync breakpoints and coordinate instances

Two fixes for debugging multi-process Ruby applications:

1. Breakpoint synchronization across forked processes (fixes #714):
   Store serialized breakpoint specs in a shared JSON tempfile alongside
   the existing flock tempfile. Publish on subsession leave, check on
   subsession enter, and in the socket reader retry paths for both DAP
   and console protocols. Breakpoints define to_sync_data for
   serialization. Only LineBreakpoint and CatchBreakpoint are synced.

2. Coordination of independent debugger instances:
   When parallel test runners fork workers before the debugger loads,
   each worker gets its own SESSION with no coordination. Add a
   well-known lock file keyed by process group ID
   (/tmp/ruby-debug-{uid}-pgrp-{getpgrp}.lock) that all sibling
   instances discover automatically. On enter_subsession, acquire
   the lock (blocking flock) so only one process enters the debugger
   at a time. While blocked, no prompt is shown and IRB/Reline never
   reads STDIN.

Author: st0012

lib/debug/breakpoint.rb

@@ -6,7 +6,7 @@ module DEBUGGER__
   class Breakpoint
     include SkipPathHelper
 
-    attr_reader :key, :skip_src
+    attr_reader :key, :skip_src, :cond
 
     def initialize cond, command, path, do_enable: true
       @deleted = false
@@ -19,6 +19,12 @@ def initialize cond, command, path, do_enable: true
       enable if do_enable
     end
 
+    # Returns a serializable hash for cross-process breakpoint sync,
+    # or nil if this breakpoint type is not syncable.
+    def to_sync_data
+      nil
+    end
+
     def safe_eval b, expr
       b.eval(expr)
     rescue Exception => e
@@ -221,6 +227,12 @@ def activate_exact iseq, events, line
       end
     end
 
+    def to_sync_data
+      { 'type' => 'line', 'path' => @path, 'line' => @line,
+        'cond' => @cond, 'oneshot' => @oneshot,
+        'hook_call' => @hook_call, 'command' => @command }
+    end
+
     def duplicable?
       @oneshot
     end
@@ -302,6 +314,10 @@ def path_is? path
   class CatchBreakpoint < Breakpoint
     attr_reader :last_exc
 
+    def to_sync_data
+      { 'type' => 'catch', 'pat' => @pat, 'cond' => @cond }
+    end
+
     def initialize pat, cond: nil, command: nil, path: nil
       @pat = pat.freeze
       @key = [:catch, @pat].freeze

lib/debug/server.rb

@@ -186,6 +186,9 @@ def process
         line = @session.process_group.sync do
           unless IO.select([@sock], nil, nil, 0)
             DEBUGGER__.debug{ "UI_Server can not read" }
+            # Wait briefly for the consuming process to publish breakpoint changes
+            sleep 0.05
+            @session.bp_sync_check
             break :can_not_read
           end
           @sock.gets&.chomp.tap{|line|

lib/debug/server_dap.rb

@@ -271,6 +271,10 @@ def recv_request
         end
       end
     rescue RetryBecauseCantRead
+      # Another process consumed the message. Wait briefly for it to
+      # process and publish any breakpoint changes, then sync.
+      sleep 0.05
+      @session.bp_sync_check
       retry
     end
 
@@ -356,6 +360,7 @@ def process_request req
               bps << SESSION.add_line_breakpoint(path, line)
             end
           }
+          SESSION.bp_sync_publish
           send_response req, breakpoints: (bps.map do |bp| {verified: true,} end)
         else
           send_response req, breakpoints: (args['breakpoints'].map do |bp| {verified: false, message: "#{req_path} could not be located; specify source location in launch.json with \"localfsMap\" or \"localfs\""} end)
@@ -391,6 +396,7 @@ def process_request req
           process_filter.call(bp_info['filterId'], bp_info['condition'])
         }
 
+        SESSION.bp_sync_publish
         send_response req, breakpoints: filters
 
       when 'disconnect'

lib/debug/session.rb

@@ -42,6 +42,7 @@
 
 require 'json' if ENV['RUBY_DEBUG_TEST_UI'] == 'terminal'
 require 'pp'
+require 'set'
 
 class RubyVM::InstructionSequence
   def traceable_lines_norec lines
@@ -90,10 +91,77 @@ module DEBUGGER__
 
   class PostmortemError < RuntimeError; end
 
+  module BreakpointSync
+    def bp_sync_publish
+      return unless @process_group.multi?
+      @process_group.write_breakpoint_state(serialize_sync_breakpoints)
+    end
+
+    def bp_sync_check
+      return false unless @process_group.multi?
+      specs = @process_group.read_breakpoint_state
+      return false unless specs
+      reconcile_breakpoints(specs)
+      true
+    end
+
+    private
+
+    def serialize_sync_breakpoints
+      @bps.filter_map { |_key, bp| bp.to_sync_data }
+    end
+
+    def reconcile_breakpoints(specs)
+      remote_keys = Set.new
+
+      specs.each do |spec|
+        key = bp_key_from_spec(spec)
+        next unless key
+        remote_keys << key
+        unless @bps.key?(key)
+          create_bp_from_spec(spec)
+        end
+      end
+
+      @bps.delete_if do |key, bp|
+        if syncable_bp?(bp) && !remote_keys.include?(key)
+          bp.delete
+          true
+        end
+      end
+    end
+
+    def bp_key_from_spec(spec)
+      case spec['type']
+      when 'line'  then [spec['path'], spec['line']]
+      when 'catch' then [:catch, spec['pat']]
+      end
+    end
+
+    def create_bp_from_spec(spec)
+      bp = case spec['type']
+           when 'line'
+             LineBreakpoint.new(spec['path'], spec['line'],
+               cond: spec['cond'], oneshot: spec['oneshot'],
+               hook_call: spec['hook_call'] != false,
+               command: spec['command'])
+           when 'catch'
+             CatchBreakpoint.new(spec['pat'], cond: spec['cond'])
+           end
+
+      add_bp(bp) if bp
+    end
+
+    def syncable_bp?(bp)
+      bp.to_sync_data != nil
+    end
+  end
+
   class Session
     attr_reader :intercepted_sigint_cmd, :process_group, :subsession_id
 
     include Color
+    include BreakpointSync
 
     def initialize
       @ui = nil
@@ -1711,8 +1779,10 @@ def get_thread_client th = Thread.current
         DEBUGGER__.debug{ "Enter subsession (nested #{@subsession_stack.size})" }
       else
         DEBUGGER__.debug{ "Enter subsession" }
+        @process_group.wk_lock  # blocks until no other debugger is active
         stop_all_threads
         @process_group.lock
+        bp_sync_check  # sync breakpoints from other processes
       end
 
       @subsession_stack << true
@@ -1724,7 +1794,9 @@ def get_thread_client th = Thread.current
 
       if @subsession_stack.empty?
         DEBUGGER__.debug{ "Leave subsession" }
+        bp_sync_publish  # publish breakpoint changes to other processes
         @process_group.unlock
+        @process_group.unlock_wk_lock
         restart_all_threads
       else
         DEBUGGER__.debug{ "Leave subsession (nested #{@subsession_stack.size})" }
@@ -2028,6 +2100,7 @@ def extend_feature session: nil, thread_client: nil, ui: nil
   class ProcessGroup
     def initialize
       @lock_file = nil
+      @wk_lock_file = nil
     end
 
     def locked?
@@ -2057,10 +2130,38 @@ def multi?
       @lock_file
     end
 
+    # No-ops for single-process mode; overridden by MultiProcessGroup
+    def write_breakpoint_state(specs); end
+    def read_breakpoint_state; nil; end
+
+    # Well-known lock for coordinating independent debugger instances
+    # (e.g., parallel test workers that each load the debugger independently).
+    # Uses process group ID so sibling processes from the same command share the lock.
+    # Blocks until the lock is acquired — other workers wait in line.
+    def wk_lock
+      return if multi?  # MultiProcessGroup handles its own locking
+      ensure_wk_lock!
+      @wk_lock_file.flock(File::LOCK_EX)
+    end
+
+    def unlock_wk_lock
+      return if multi?
+      @wk_lock_file&.flock(File::LOCK_UN)
+    end
+
+    private def ensure_wk_lock!
+      return if @wk_lock_file
+      path = File.join('/tmp', "ruby-debug-#{Process.uid}-pgrp-#{Process.getpgrp}.lock")
+      @wk_lock_file = File.open(path, File::WRONLY | File::CREAT, 0600)
+    end
+
     def multi_process!
       require 'tempfile'
+      require 'json'
       @lock_tempfile = Tempfile.open("ruby-debug-lock-")
       @lock_tempfile.close
+      @state_tempfile = Tempfile.open("ruby-debug-state-")
+      @state_tempfile.close
       extend MultiProcessGroup
     end
   end
@@ -2076,6 +2177,7 @@ def after_fork child: true
           @lock_level = 0
           @lock_file = open(@lock_tempfile.path, 'w')
         end
+        @bp_sync_version = 0
       end
     end
 
@@ -2146,6 +2248,25 @@ def unlock
       end
     end
 
+    def write_breakpoint_state(specs)
+      @bp_sync_version += 1
+      data = JSON.generate({ 'v' => @bp_sync_version, 'bps' => specs })
+      tmp = "#{@state_tempfile.path}.#{Process.pid}.tmp"
+      File.write(tmp, data)
+      File.rename(tmp, @state_tempfile.path)
+    end
+
+    def read_breakpoint_state
+      return nil unless File.exist?(@state_tempfile.path)
+      data = JSON.parse(File.read(@state_tempfile.path))
+      remote_v = data['v']
+      return nil if remote_v <= @bp_sync_version
+      @bp_sync_version = remote_v
+      data['bps']
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
     def sync &b
       info "sync"
 
@@ -2547,6 +2668,7 @@ def daemon(*args)
         child_hook = -> {
           DEBUGGER__.info "Attaching after process #{parent_pid} fork to child process #{Process.pid}"
           SESSION.process_group.after_fork child: true
+          SESSION.bp_sync_check
           SESSION.activate on_fork: true
         }
       end