galaaz 2.1.3 → 2.1.5

data/lib/R_interface/r_job.rb

@@ -0,0 +1,429 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'securerandom'
+require 'time'
+
+module R
+  # Background R work in a **child Rscript process** (not the NewBridge gatekeeper).
+  #
+  # Layer B — installs:
+  #   job = R::Job.install('caret')
+  #   job.raise_if_failed!
+  #
+  # Layer C — long arbitrary R (bridge stays free). Default +wait: true+ awaits
+  # before returning; with a block, await, yield the job, return the block value:
+  #
+  #   coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  #     fit <- lm(mpg ~ wt, data = mtcars)
+  #     saveRDS(coef(fit), result_path)
+  #   R
+  #
+  #   job = R::Job.script('train.R', 'arg1')           # awaits, returns Job
+  #   job = R::Job.eval(code, wait: false)             # start only
+  #
+  class Job
+    class Error < StandardError; end
+    class Failed < Error; end
+    class Timeout < Error; end
+
+    DEFAULT_REPOS = 'https://cloud.r-project.org'
+    DEFAULT_LIB = File.expand_path('~/R/x86_64-pc-linux-gnu-library/galaaz')
+    JOBS_ROOT = File.expand_path('~/.local/share/galaaz/jobs')
+    DEFAULT_RESULT_NAME = 'result.rds'
+
+    attr_reader :id, :kind, :dir, :log_path, :meta_path, :pid, :packages, :lib_dir,
+                :script_path, :script_args
+
+    def self.jobs_root
+      ENV['GALAAZ_JOBS_DIR'] && !ENV['GALAAZ_JOBS_DIR'].empty? ? File.expand_path(ENV['GALAAZ_JOBS_DIR']) : JOBS_ROOT
+    end
+
+    def self.default_lib_dir
+      DEFAULT_LIB
+    end
+
+    # Install one or more CRAN packages in a child Rscript, then optionally await.
+    #
+    # With a block: always await, +raise_if_failed!+, yield the job, return the
+    # block's value (File.open-style). Without a block: return the +Job+ (awaits
+    # when +wait:+ is true, the default).
+    #
+    # @param packages [String, Array<String>]
+    # @param lib_dir [String] install library (added to .libPaths in the child)
+    # @param repos [String] CRAN mirror
+    # @param wait [Boolean] if true (default), block until the job finishes
+    # @param timeout [nil, Numeric] await wall-clock seconds; nil = wait forever
+    # @return [R::Job, Object] Job, or the block's return value
+    def self.install(*packages, lib_dir: default_lib_dir, repos: DEFAULT_REPOS, wait: true, timeout: nil, &block)
+      pkgs = packages.flatten.map(&:to_s).reject(&:empty?)
+      raise ArgumentError, 'R::Job.install requires at least one package name' if pkgs.empty?
+
+      FileUtils.mkdir_p(lib_dir)
+      FileUtils.mkdir_p(jobs_root)
+
+      with_install_lock do
+        job = new(kind: 'install', packages: pkgs, lib_dir: lib_dir)
+        job.send(:spawn_install!, repos: repos)
+        finish_job(job, wait: wait, timeout: timeout, &block)
+      end
+    end
+
+    # Run arbitrary R code in a child Rscript (Layer C).
+    #
+    # The child starts with +lib_dir+ on +.libPaths+, +setwd(job.dir)+, and:
+    #   GALAAZ_JOB_DIR  — job directory
+    #   result_path     — default +file.path(GALAAZ_JOB_DIR, "result.rds")+
+    # Persist outputs with +saveRDS(..., result_path)+ (or any path under +job.dir+),
+    # then load on the bridge with +job.load_rds+.
+    #
+    # With a block: await, raise on failure, yield job, return block value.
+    #
+    # @param code [String] R source
+    # @param lib_dir [String]
+    # @param wait [Boolean]
+    # @param timeout [nil, Numeric]
+    # @return [R::Job, Object]
+    def self.eval(code, lib_dir: default_lib_dir, wait: true, timeout: nil, &block)
+      raise ArgumentError, 'R::Job.eval requires code' if code.nil? || code.to_s.strip.empty?
+
+      FileUtils.mkdir_p(lib_dir)
+      FileUtils.mkdir_p(jobs_root)
+
+      job = new(kind: 'eval', packages: [], lib_dir: lib_dir)
+      job.send(:spawn_eval!, code)
+      finish_job(job, wait: wait, timeout: timeout, &block)
+    end
+
+    # Run an R script file in a child Rscript (Layer C).
+    #
+    # With a block: await, raise on failure, yield job, return block value.
+    #
+    # @param path [String] path to +.R+ file
+    # @param args [Array<String>] trailing args (+commandArgs(trailingOnly=TRUE)+)
+    # @param lib_dir [String]
+    # @param wait [Boolean]
+    # @param timeout [nil, Numeric]
+    # @return [R::Job, Object]
+    def self.script(path, *args, lib_dir: default_lib_dir, wait: true, timeout: nil, &block)
+      script = File.expand_path(path.to_s)
+      raise ArgumentError, "R::Job.script: file not found: #{script}" unless File.file?(script)
+
+      FileUtils.mkdir_p(lib_dir)
+      FileUtils.mkdir_p(jobs_root)
+
+      job = new(kind: 'script', packages: [], lib_dir: lib_dir, script_path: script, script_args: args.map(&:to_s))
+      job.send(:spawn_script!)
+      finish_job(job, wait: wait, timeout: timeout, &block)
+    end
+
+    # @api private
+    def self.finish_job(job, wait:, timeout:, &block)
+      job.wait(timeout: timeout) if wait || block
+      if block
+        job.raise_if_failed!
+        return yield(job)
+      end
+      job
+    end
+    private_class_method :finish_job
+
+    def initialize(kind:, packages:, lib_dir:, script_path: nil, script_args: [])
+      @kind = kind.to_s
+      @packages = packages
+      @lib_dir = File.expand_path(lib_dir)
+      @script_path = script_path
+      @script_args = script_args || []
+      @id = "#{@kind}-#{Time.now.utc.strftime('%Y%m%dT%H%M%S')}-#{Process.pid}-#{SecureRandom.hex(3)}"
+      @dir = File.join(self.class.jobs_root, @id)
+      FileUtils.mkdir_p(@dir)
+      @log_path = File.join(@dir, 'job.log')
+      @meta_path = File.join(@dir, 'meta.json')
+      @exit_path = File.join(@dir, 'exit_code')
+      @pid = nil
+      @exit_status = nil
+    end
+
+    def status
+      return :ok if finished? && exit_code == 0
+      return :failed if finished? && exit_code != 0
+      return :running if alive?
+
+      :unknown
+    end
+
+    def alive?
+      return false unless @pid
+
+      begin
+        Process.kill(0, @pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+    end
+
+    def finished?
+      return true unless @exit_status.nil?
+      return true if File.file?(@exit_path) && !alive?
+
+      false
+    end
+
+    def exit_code
+      return @exit_status.exitstatus if @exit_status.respond_to?(:exitstatus)
+      return File.read(@exit_path).to_i if File.file?(@exit_path)
+
+      nil
+    end
+
+    # Default RDS path written by child when using +result_path+ / +saveRDS(..., result_path)+.
+    def result_path(name = DEFAULT_RESULT_NAME)
+      File.join(@dir, name.to_s)
+    end
+
+    # Await process completion.
+    # @param timeout [nil, Numeric] nil = forever
+    # @return [Symbol] final status (:ok or :failed)
+    def wait(timeout: nil)
+      return status if finished?
+
+      if timeout.nil?
+        reap!
+      else
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + Float(timeout)
+        loop do
+          reap_nonblock!
+          break if finished?
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            kill!
+            raise Timeout, "R::Job #{@id} still running after #{timeout}s (pid=#{@pid}, log=#{@log_path})"
+          end
+
+          sleep 0.2
+        end
+      end
+
+      write_exit_file!
+      status
+    end
+
+    def raise_if_failed!
+      st = status
+      return self if st == :ok
+
+      if st == :running
+        raise Error, "R::Job #{@id} is still running (pid=#{@pid}, log=#{@log_path})"
+      end
+
+      tail = File.readable?(@log_path) ? File.read(@log_path).lines.last(40).join : ''
+      raise Failed, "R::Job #{@id} failed (exit=#{exit_code}, log=#{@log_path})\n--- log tail ---\n#{tail}"
+    end
+
+    # Short sync +readRDS+ on the **bridge** after a successful job.
+    # Returns a normal Galaaz R object (same as +R.readRDS(...)+).
+    # @param name [String] file under +job.dir+ (default +result.rds+)
+    def load_rds(name = DEFAULT_RESULT_NAME)
+      raise_if_failed!
+      path = result_path(name)
+      raise Error, "R::Job #{@id}: result not found: #{path}" unless File.file?(path)
+
+      R.readRDS(path)
+    end
+
+    def kill!(signal = 'TERM')
+      return unless @pid
+
+      # Spawned with pgroup: true — kill the whole process group (Rscript + make/gcc).
+      targets = [-@pid, @pid]
+      targets.each do |t|
+        begin
+          Process.kill(signal, t)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+      sleep 0.2
+      targets.each do |t|
+        begin
+          Process.kill('KILL', t)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+      reap_nonblock!
+      write_exit_file!
+    end
+
+    def self.with_install_lock
+      FileUtils.mkdir_p(jobs_root)
+      lock_path = File.join(jobs_root, 'install.lock')
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lf|
+        lf.flock(File::LOCK_EX)
+        yield
+      ensure
+        lf.flock(File::LOCK_UN) rescue nil
+      end
+    end
+
+    private
+
+    def spawn_install!(repos:)
+      # Stale 00LOCK-* dirs remain after kill!-on-timeout and block the next install.
+      @packages.each do |pkg|
+        lock = File.join(@lib_dir, "00LOCK-#{pkg}")
+        FileUtils.rm_rf(lock) if File.exist?(lock)
+      end
+
+      pkg_list = @packages.map { |p| "'#{p.gsub("'", "\\\\'")}'" }.join(', ')
+      lib_esc = @lib_dir.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+      repos_esc = repos.gsub("'", "\\\\'")
+      r_code = <<~R
+        lib <- '#{lib_esc}'
+        dir.create(lib, recursive = TRUE, showWarnings = FALSE)
+        .libPaths(c(lib, .libPaths()))
+        Sys.setenv(MAKEFLAGS = '-j1')
+        options(Ncpus = 1L, repos = '#{repos_esc}')
+        pkgs <- c(#{pkg_list})
+        message('R::Job install starting: ', paste(pkgs, collapse = ', '))
+        message('lib = ', lib)
+        install.packages(pkgs, lib = lib, dependencies = NA)
+        missing <- pkgs[!pkgs %in% rownames(installed.packages(lib.loc = lib))]
+        if (length(missing)) {
+          message('Still missing after install: ', paste(missing, collapse = ', '))
+          quit(status = 1)
+        }
+        message('R::Job install OK')
+        quit(status = 0)
+      R
+      spawn_rscript!(r_code)
+    end
+
+    def spawn_eval!(code)
+      preamble = child_preamble_r
+      r_code = <<~R
+        #{preamble}
+        message('R::Job eval starting')
+        tryCatch({
+        #{indent_r(code, 2)}
+        }, error = function(e) {
+          message('R::Job eval error: ', conditionMessage(e))
+          quit(status = 1)
+        })
+        message('R::Job eval OK')
+        quit(status = 0)
+      R
+      spawn_rscript!(r_code)
+    end
+
+    def spawn_script!
+      preamble = child_preamble_r
+      script_esc = @script_path.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+      # Persist user script path in job dir for forensics; execution uses absolute path.
+      FileUtils.cp(@script_path, File.join(@dir, File.basename(@script_path))) rescue nil
+      r_code = <<~R
+        #{preamble}
+        message('R::Job script starting: #{script_esc}')
+        tryCatch({
+          source('#{script_esc}', local = FALSE)
+        }, error = function(e) {
+          message('R::Job script error: ', conditionMessage(e))
+          quit(status = 1)
+        })
+        message('R::Job script OK')
+        quit(status = 0)
+      R
+      spawn_rscript!(r_code, extra_args: @script_args)
+    end
+
+    def child_preamble_r
+      lib_esc = @lib_dir.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+      dir_esc = @dir.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+      <<~R
+        lib <- '#{lib_esc}'
+        job_dir <- '#{dir_esc}'
+        dir.create(lib, recursive = TRUE, showWarnings = FALSE)
+        dir.create(job_dir, recursive = TRUE, showWarnings = FALSE)
+        .libPaths(c(lib, .libPaths()))
+        setwd(job_dir)
+        Sys.setenv(MAKEFLAGS = '-j1', GALAAZ_JOB_DIR = job_dir)
+        options(Ncpus = 1L)
+        result_path <- file.path(job_dir, '#{DEFAULT_RESULT_NAME}')
+      R
+    end
+
+    def indent_r(code, spaces)
+      pad = ' ' * spaces
+      code.to_s.gsub("\r\n", "\n").lines.map { |line| "#{pad}#{line}" }.join
+    end
+
+    def spawn_rscript!(r_code, extra_args: [])
+      wrapper_path = File.join(@dir, 'job.R')
+      File.write(wrapper_path, r_code)
+      log_io = File.open(@log_path, File::WRONLY | File::CREAT | File::TRUNC)
+      rscript = ENV['GALAAZ_RSCRIPT'] && !ENV['GALAAZ_RSCRIPT'].empty? ? ENV['GALAAZ_RSCRIPT'] : 'Rscript'
+      env = {
+        'MAKEFLAGS' => '-j1',
+        'GALAAZ_JOB_DIR' => @dir,
+        'R_LIBS_USER' => @lib_dir
+      }
+      cmd = [rscript, '--vanilla', wrapper_path, *extra_args.map(&:to_s)]
+      @pid = spawn(env, *cmd, out: log_io, err: log_io, pgroup: true, chdir: @dir)
+      log_io.close
+      write_meta!
+      $stderr.puts "[RUBY] R::Job #{@id} started pid=#{@pid} log=#{@log_path}"
+    end
+
+    def write_meta!
+      File.write(@meta_path, JSON.pretty_generate(
+        id: @id,
+        kind: @kind,
+        packages: @packages,
+        lib_dir: @lib_dir,
+        dir: @dir,
+        script_path: @script_path,
+        script_args: @script_args,
+        pid: @pid,
+        log_path: @log_path,
+        result_path: result_path,
+        started_at: Time.now.utc.iso8601
+      ))
+    end
+
+    def write_exit_file!
+      code = exit_code
+      File.write(@exit_path, code.nil? ? "-1\n" : "#{code}\n") unless code.nil?
+    end
+
+    def reap!
+      return if @exit_status
+
+      _pid, @exit_status = Process.wait2(@pid)
+    rescue Errno::ECHILD
+      @exit_status = read_fake_status_from_file
+    end
+
+    def reap_nonblock!
+      return if @exit_status
+
+      pid, st = Process.wait2(@pid, Process::WNOHANG)
+      @exit_status = st if pid
+    rescue Errno::ECHILD
+      @exit_status = read_fake_status_from_file if File.file?(@exit_path)
+    end
+
+    def read_fake_status_from_file
+      return nil unless File.file?(@exit_path)
+
+      code = File.read(@exit_path).to_i
+      # Minimal stand-in with exitstatus
+      Object.new.tap do |o|
+        o.define_singleton_method(:exitstatus) { code }
+        o.define_singleton_method(:success?) { code.zero? }
+      end
+    end
+  end
+end

data/lib/galaaz/cli.rb

@@ -285,6 +285,14 @@ module Galaaz
     end
 
     def add_knit
+      unless command_present?('pandoc')
+        raise CliError,
+              'pandoc not on PATH (rmarkdown/gknit need pandoc >= 2.8). ' \
+              'Omarchy: omarchy-pkg-add pandoc   Arch: pacman -S pandoc   Debian: apt install pandoc'
+      end
+      ver = `pandoc --version 2>/dev/null`.lines.first.to_s.strip
+      puts "galaaz add knit: #{ver.empty? ? 'pandoc OK' : ver}"
+
       pkgs = read_pkg_list('knit.txt')
       install_cran!(pkgs)
       extras_path = File.join(root, 'r_requires', 'knit-extras.txt')
@@ -296,11 +304,23 @@ module Galaaz
       end
       mark_profile!('knit')
       puts 'galaaz add knit: OK'
-      puts 'You can now run: gknit ~/galaaz-blogs/oh_my/oh_my.Rmd'
+      puts 'Example knits (after blogs init → ~/galaaz-blogs):'
+      puts '  gknit ~/galaaz-blogs/oh_my/oh_my.Rmd'
+      puts '  gknit ~/galaaz-blogs/galaaz_ggplot/galaaz_ggplot.Rmd'
+      puts '  gknit ~/galaaz-blogs/gknit/gknit.Rmd'
+      puts 'Docs: https://rbotafogo.github.io/galaaz/'
+      puts '      https://github.com/rbotafogo/galaaz'
+      puts 'Omarchy menu: Guide (what\'s next) · Knit demo (oh_my)'
       0
     end
 
     def add_arrow
+      # R 'arrow' needs a matching libarrow. Compiling Arrow C++ + Boost from the
+      # CRAN source tarball is fragile (especially Arch/Omarchy). Distro libarrow
+      # (e.g. Arch extra/arrow) often mismatches the CRAN package major and then
+      # pkg-config configure fails. Apache's version-matched prebuilt libarrow is
+      # the reliable automated path — HTTPS from Apache, no interactive steps.
+      prepare_arrow_cran_env!
       pkgs = read_pkg_list('arrow.txt')
       install_cran!(pkgs)
       if RUBY_ENGINE == 'ruby'
@@ -316,6 +336,17 @@ module Galaaz
       0
     end
 
+    # Env for install.packages("arrow") — see https://arrow.apache.org/docs/r/articles/install.html
+    def prepare_arrow_cran_env!
+      ENV['LIBARROW_BINARY'] = 'true'
+      ENV['NOT_CRAN'] = 'true'
+      # Do not fall back to the Boost/C++ source build that breaks on Arch.
+      ENV['LIBARROW_BUILD'] = 'false'
+      # Avoid linking against a mismatched system libarrow (e.g. pacman 24.x vs CRAN 25.x).
+      ENV['ARROW_USE_PKG_CONFIG'] = 'false'
+      puts 'galaaz add arrow: LIBARROW_BINARY=true (Apache prebuilt libarrow; no source build)'
+    end
+
     def add_tex
       unless command_present?('pandoc')
         warn 'galaaz add tex: pandoc not on PATH — install via your package manager (e.g. pacman -S pandoc)'
@@ -386,20 +417,21 @@ module Galaaz
         abort_unless(ok, 'git clone failed (is the ledger repo public/reachable?)')
       end
 
-      gemfile = File.join(dest, 'Gemfile')
-      text = File.read(gemfile)
-      rewritten = text.gsub(/gem\s+["']galaaz["']\s*,\s*path:\s*["'][^"']+["']/, 'gem "galaaz"')
-      if rewritten != text
-        File.write(gemfile, rewritten)
-        puts 'galaaz add ledger: Gemfile now uses RubyGems galaaz (no path:)'
-      end
+      ensure_ledger_galaaz_gemfile!(File.join(dest, 'Gemfile'))
 
       Dir.chdir(dest) do
         need_cmd!('bundle')
-        abort_unless(system('bundle', 'install'), 'bundle install failed')
-        # Ensure gatekeeper for the bundled/installed gem path when possible.
-        system('galaaz', 'setup') || warn('galaaz add ledger: galaaz setup returned non-zero; check gatekeeper')
+        # Lockfile often still pins path: ../galaaz @ an old version — pull latest RubyGems.
+        puts 'galaaz add ledger: bundle update galaaz'
+        unless system('bundle', 'update', 'galaaz')
+          abort_unless(system('bundle', 'install'), 'bundle install failed')
+        end
+        # Setup the gem Bundler will load (not PATH galaaz, which may differ).
+        puts 'galaaz add ledger: bundle exec galaaz setup'
+        system('bundle', 'exec', 'galaaz', 'setup') ||
+          warn('galaaz add ledger: bundle exec galaaz setup returned non-zero; check gatekeeper')
         abort_unless(system('bin/rails', 'db:prepare'), 'rails db:prepare failed')
+        abort_unless(system('bin/rails', 'db:migrate'), 'rails db:migrate failed')
         abort_unless(system({ 'SEED_PROFILE' => 'fast' }, 'bin/rails', 'db:seed'), 'rails db:seed failed')
       end
 
@@ -410,6 +442,21 @@ module Galaaz
       0
     end
 
+    # Ledger repo may ship `gem "galaaz", path: "..."`. Standalone installs use RubyGems
+    # (CRuby or JRuby), unpinned, so `bundle update galaaz` takes the newest published gem.
+    def ensure_ledger_galaaz_gemfile!(gemfile)
+      text = File.read(gemfile)
+      line = 'gem "galaaz"'
+      rewritten = text.gsub(/^\s*gem\s+["']galaaz["'].*$/, line)
+      if rewritten == text && text !~ /^\s*gem\s+["']galaaz["']/
+        rewritten = text + "\n#{line}\n"
+      end
+      if rewritten != text
+        File.write(gemfile, rewritten)
+        puts 'galaaz add ledger: Gemfile → gem "galaaz" (RubyGems latest; not path:)'
+      end
+    end
+
     # ---- helpers ----
 
     class CliError < StandardError; end

data/lib/gknit/diagnostics.rb

@@ -9,7 +9,9 @@ module GknitDiagnostics
     /invalid connection/i,
     /galaaz_callback_call timeout/i,
     /NewBridge::SessionClient::/i,
-    /Unsupported graphics device/i
+    /Unsupported graphics device/i,
+    /install job timed out/i,
+    /R::Job .+ still running after/i
   ].freeze
 
   def self.reset!

data/lib/new_bridge/session_client.rb

@@ -109,6 +109,8 @@ module NewBridge
       @r_stderr_mx = Mutex.new
       @r_stderr_limit = 64 * 1024
       @r_exit_status = nil
+      @r_wait_thr = nil
+      @r_thr = nil
     end
 
     # Whether to use Unix domain sockets for this client when +use_unix+ is nil.
@@ -190,6 +192,7 @@ module NewBridge
       @r_thr = Thread.new do
         launch = @r_cmd.is_a?(Array) ? @r_cmd.dup : [@r_cmd]
         _stdin, stdout_err, wait_thr = Open3.popen2e(env, *launch, '--slave', '--no-save', '-e', r_script)
+        @r_wait_thr = wait_thr
         # When the R process exits or during shutdown, the underlying pipe can
         # close while this background thread is still blocked reading.
         # Treat that as a normal shutdown and avoid JRuby "stream closed in
@@ -216,12 +219,40 @@ module NewBridge
         tail = details.length > 2000 ? details[-2000, 2000] : details
         msg += " stderr_tail=#{tail}"
       end
+      kill_runtime_process!
       raise RProcessError, msg
     end
 
+    # Hard-stop the R child (e.g. after an eval timeout while install.packages is still compiling).
+    # Without this, R keeps building packages and can OOM the host shell/VM.
+    def kill_runtime_process!
+      thr = @r_wait_thr
+      pid = begin
+        thr&.pid
+      rescue StandardError
+        nil
+      end
+      if pid
+        begin
+          Process.kill('TERM', pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+        sleep 0.2
+        begin
+          Process.kill('KILL', pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+    ensure
+      @r_wait_thr = nil
+    end
+
     # Stop the client and attempt to join threads cleanly.
     # Best-effort: socket/server are closed, reader thread is joined, runtime thread is joined.
     def stop
+      kill_runtime_process!
       @sock&.close rescue nil
       @server&.close rescue nil
       if @unix_path && File.socket?(@unix_path)
@@ -232,6 +263,20 @@ module NewBridge
       @r_thr&.join(15)
     end
 
+    # Kill R + reopen listener/runtime. Clears pending queues.
+    def restart!(accept_timeout: 120)
+      stop
+      @pending_mx.synchronize { @pending.clear }
+      @callbacks_mx.synchronize { @callbacks.clear }
+      @r_stderr_mx.synchronize { @r_stderr = +'' }
+      @r_exit_status = nil
+      @reader = nil
+      @r_thr = nil
+      @sock = nil
+      @server = nil
+      start(accept_timeout: accept_timeout)
+    end
+
     # Evaluate one REQ on the connected R runtime and wait for the matching RET.
     #
     # @param code [String] R expression or snippet to be evaluated by the gatekeeper.