galaaz 2.1.3 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '085fd47fe76016fb5b078f3c44a02100a7d9af05c2f7cf9e19ded83058947c8e'
-  data.tar.gz: 19f36b20968fd4456ad95024f2a33dbde60dfdf62a3bbda295d49e08a8c32bc7
+  metadata.gz: 03ba582ba7054d11d6ce78bd5bf50fc424aac1a391209dee52749dd6bb642677
+  data.tar.gz: a9997f60ab4446b6ecdbda2cfa32a1f9de03fb002b8d2bdc5df945043fe547ab
 SHA512:
-  metadata.gz: c7db477fca2f6de435d9eb6bd5ccc5ee709a779e3a5816febc9a0eda9be51f5f18812af79889e7fd4ce1e5facd79a080e80a98829381b19670d6a380765554c4
-  data.tar.gz: 6ba4144e49328b6bb70188ab6330ed086f969cb952076758db0207171c54c2ff41e6fb21c8666a6cd87b459f47b2786a31edf8f1f1b98343d7d536aae902de36
+  metadata.gz: fcbc2a6d680c73df54768ff9a623d11f3c4723f030416f8d0937183fef4247b66982aa5bc7c0600d97ade5b9a67e7a6b17eecd7c8e7f507d0528510086fd33db
+  data.tar.gz: fa9b17e4e135ea1a199b76103f5f86739312816dee9e3fae332fa9e0773b6eb80124bd1f37a65759afdd610bc5a7fb9d4eba2c928c08adfd730aaf37f17899b8

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.1.4
+
+### Added
+
+- **`R::Job`**: long CRAN installs (and arbitrary R via `R::Job.eval`) run in a **child
+  Rscript** process, not on the NewBridge gatekeeper. Logs and metadata live under
+  `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`). One install at a
+  time (`install.lock`). Bridge R stays free while Ruby awaits the job. Clears stale
+  `00LOCK-<pkg>` dirs before install (left behind after kill-on-timeout).
+- **Layer C:** `R::Job.eval` / `R::Job.script` for long arbitrary R. Child gets
+  `setwd(job.dir)`, `GALAAZ_JOB_DIR`, and `result_path` (default `result.rds`). After
+  success, `job.load_rds` does a short sync `readRDS` on the bridge. Block form
+  awaits and yields the job (`coef = R::Job.eval(code) { |j| j.load_rds }`).
+  Documented in the manual section **Background R jobs (`R::Job`)** (README /
+  `blogs/manual/manual.Rmd`).
+
+### Changed
+
+- `R.install_rlibs` / `R.install_and_loads` use `R::Job.install` and **await until
+  finished** by default (no bridge 60s install timeout). Optional await limit via
+  `install_timeout_sec:` or `GALAAZ_INSTALL_TIMEOUT_SEC` (also `gknit
+  --install_timeout_sec`); on timeout the child process group is killed so compile
+  work cannot OOM the shell. gknit reports install-job timeouts in the internal
+  error summary.
+
 ## 2.1.3
 
 ### Fixed
@@ -85,4 +110,6 @@ Galaaz 2.0 drives **GNU R** from **JRuby** or **CRuby** over a process bridge. I
 - `grun`, `gknit_Rscript`, and the polyglot path in `gknit-draft` are leftover from the Graal era; use `galaaz-jruby` / `gknit` (or `GALAAZ_RUBY=ruby` for CRuby).
 - The gatekeeper must be compiled on the install machine (Rcpp + C++ toolchain); it is not a prebuilt binary in the gem.
 - Multi-runtime Docker R (Phase 4.5) is a slow integration spec, not part of cold-install CI.
-- The gknit installation-timeout spec is skipped pending a dedicated pass; SimpleCov is a development gem and is not installed in the smoke image.
+- The gknit installation-timeout spec covers `R::Job` await timeouts
+  (`GALAAZ_INSTALL_TIMEOUT_SEC`); SimpleCov is a development gem and is not installed in
+  the smoke image.

data/README.md

@@ -73,7 +73,7 @@ rewrite in another stack. **R-on-Rails** means:
 1. **Keep your science in R** — packages, formulas, plots, Bioconductor, the same engine as RStudio.
 2. **Learn enough Ruby/Rails** — routes, controllers, views, jobs, auth—not a second statistics career.
 3. **Call R from the app** — Galaaz loads R behind the scenes; long jobs can complete asynchronously
-   while Rails stays responsive (see later sections on the bridge and `R::Async`).
+   while Rails stays responsive (see later sections on the bridge, `R::Async`, and `R::Job`).
 4. **Ship alone when you need to** — one developer can own both the analysis and the product UI,
    without waiting for a separate “stats engineer” and “Rails engineer.”
 
@@ -456,8 +456,13 @@ driver). For concurrency tests on the bridge itself, see `specs/bridge_concurren
 
 ## Long-running R calls and a completion block
 
-For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by
-scheduling the call and resuming in a **block** when the `RET` arrives.
+For R work that can take a long time **on the bridge**, the bridge can avoid a Ruby-side
+**wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives.
+
+**Important distinction:** this keeps the **same** GNU R process busy. Other sync
+`eval_r` / gknit chunks still wait on that R. For CRAN installs and other work that must
+**not** monopolize the bridge (or that can OOM a small VM if abandoned mid-compile), use
+**`R::Job`** in the next section instead.
 
 - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value`
   is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit).
@@ -514,6 +519,67 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
+## Background R jobs (`R::Job`)
+
+`R::Async` / `R.eval_r_async` free the **Ruby** thread while the **same** bridge R process
+runs your code. That is enough for Rails-style “don’t block the request thread,” but not
+enough for heavy `install.packages` or multi-minute model fits: the gatekeeper R is still
+busy, other chunks time out, and abandoning the wait can leave compile work burning RAM.
+
+**`R::Job`** runs that work in a **child `Rscript` process**. The bridge stays free. Logs and
+metadata live under `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`).
+
+### Package installs
+
+`R.install_and_loads` / `R.install_rlibs` use `R::Job.install` and **await until the child
+finishes** (default: no wall-clock limit). Optional limit: `GALAAZ_INSTALL_TIMEOUT_SEC` or
+`install_timeout_sec:`. On timeout the child process group is killed so leftover
+`make`/`gcc` cannot OOM the shell. Stale `00LOCK-*` dirs are cleared before the next install.
+Only one install runs at a time (`install.lock`).
+
+``` ruby
+# May take a long time the first time (e.g. caret); the bridge is not used for compile.
+R.install_and_loads 'caret'
+```
+
+### Long arbitrary R (`eval` / `script`)
+
+Prefer the **block** form (like `File.open`): await the child, yield the job, return the
+block’s value. Without a block, the methods still await by default and return the `Job`.
+
+``` ruby
+coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  fit <- lm(mpg ~ wt, data = mtcars)
+  saveRDS(unname(coef(fit)), result_path)
+R
+puts coef
+```
+
+```
+## [1] 37.285126 -5.344472
+```
+
+``` ruby
+# Without a block: awaits (wait: true is the default) and returns the Job
+job = R::Job.eval(code)
+job = R::Job.eval(code, wait: false)  # start only; call job.wait later
+
+# Script file; trailing args → commandArgs(trailingOnly=TRUE) in the child
+res = R::Job.script('train.R', '5') { |job| job.load_rds }
+```
+
+In the child: `setwd(job.dir)`, `.libPaths` includes the Galaaz user library,
+`GALAAZ_JOB_DIR` is set, and **`result_path`** defaults to
+`file.path(GALAAZ_JOB_DIR, "result.rds")`. Persist with `saveRDS(..., result_path)`, then
+load on the bridge with **`job.load_rds`** (short sync `readRDS` → a normal Galaaz R object).
+
+### Choosing async vs Job
+
+| Need | Use |
+|------|-----|
+| Don’t freeze a Ruby thread; short/medium R on the bridge is OK | `R::Async` / `R.eval_r_async` |
+| Install CRAN packages, or long R that must not block the bridge | `R::Job` / `R.install_and_loads` |
+
 ## Galaaz + Rails (R-on-Rails) integration baseline
 
 This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
@@ -1873,7 +1939,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}

data/bin/gknit

@@ -65,9 +65,12 @@ that are created during rendering.") do |opt|
   opts.on("--callback_timeout_ms TIMEOUT_MS", Integer, "Callback timeout in milliseconds for R<->Ruby calls inside chunk execution. Use for long installs/computation (e.g., 7200000 for 2h).") do |opt|
     options[:callback_timeout_ms] = opt
   end
-  opts.on("--bridge_timeout_sec TIMEOUT_SEC", Integer, "Bridge request timeout in seconds for Ruby->R eval calls (default 60). Increase for long install.packages/compilation work.") do |opt|
+  opts.on("--bridge_timeout_sec TIMEOUT_SEC", Integer, "Bridge request timeout in seconds for Ruby->R eval calls (default 60). For CRAN installs via R::Job, use GALAAZ_INSTALL_TIMEOUT_SEC instead.") do |opt|
     options[:bridge_timeout_sec] = opt
   end
+  opts.on("--install_timeout_sec TIMEOUT_SEC", Integer, "Await limit in seconds for R::Job package installs (sets GALAAZ_INSTALL_TIMEOUT_SEC). Default: wait until the child finishes.") do |opt|
+    options[:install_timeout_sec] = opt
+  end
 end
 
 remaining_args = parser.permute(ARGV.dup)
@@ -153,6 +156,7 @@ input_dir = File.dirname(input_file)
 code = <<EOF
 ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = #{options[:callback_timeout_ms].to_s.inspect} if #{!options[:callback_timeout_ms].nil?}
 ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = #{options[:bridge_timeout_sec].to_s.inspect} if #{!options[:bridge_timeout_sec].nil?}
+ENV['GALAAZ_INSTALL_TIMEOUT_SEC'] = #{options[:install_timeout_sec].to_s.inspect} if #{!options[:install_timeout_sec].nil?}
 require %q(galaaz)
 require %q(gknit)
 
@@ -199,6 +203,11 @@ Dir.chdir(#{input_dir.inspect}) do
       STDERR.puts "Likely bridge timeout during long-running Ruby->R evaluation."
       STDERR.puts "Current bridge timeout: \#{bridge_sec} sec; callback timeout: \#{callback_ms} ms."
       STDERR.puts "Use gknit --bridge_timeout_sec <sec> and/or --callback_timeout_ms <ms> for longer operations."
+    elsif e.message.to_s.match?(/install job timed out/i)
+      install_sec = ENV['GALAAZ_INSTALL_TIMEOUT_SEC'] || '(none - wait until done)'
+      STDERR.puts "Likely R::Job install await timeout."
+      STDERR.puts "Current GALAAZ_INSTALL_TIMEOUT_SEC: \#{install_sec}."
+      STDERR.puts "Use gknit --install_timeout_sec <sec> (or unset it to wait forever), or install the package outside gknit."
     end
     if missing_pkg
       STDERR.puts "Likely missing LaTeX package: \#{missing_pkg} (install with tlmgr)."
@@ -218,6 +227,7 @@ libx = File.expand_path('../lib', File.dirname(__FILE__))
 require File.join(libx, 'galaaz_ruby')
 ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = options[:callback_timeout_ms].to_s if !options[:callback_timeout_ms].nil?
 ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = options[:bridge_timeout_sec].to_s if !options[:bridge_timeout_sec].nil?
+ENV['GALAAZ_INSTALL_TIMEOUT_SEC'] = options[:install_timeout_sec].to_s if !options[:install_timeout_sec].nil?
 exec "#{GalaazRuby.shell_invocation(libx)} -e #{Shellwords.escape(code)}"
 
 =begin

data/blogs/gknit/gknit.Rmd

@@ -610,7 +610,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}`r ''`

data/blogs/gknit/gknit.md

@@ -1166,7 +1166,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}

data/blogs/manual/manual.Rmd

@@ -371,8 +371,13 @@ driver). For concurrency tests on the bridge itself, see `specs/bridge_concurren
 
 ## Long-running R calls and a completion block
 
-For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by
-scheduling the call and resuming in a **block** when the `RET` arrives.
+For R work that can take a long time **on the bridge**, the bridge can avoid a Ruby-side
+**wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives.
+
+**Important distinction:** this keeps the **same** GNU R process busy. Other sync
+`eval_r` / gknit chunks still wait on that R. For CRAN installs and other work that must
+**not** monopolize the bridge (or that can OOM a small VM if abandoned mid-compile), use
+**`R::Job`** in the next section instead.
 
 - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value`
   is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit).
@@ -420,6 +425,63 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
+## Background R jobs (`R::Job`)
+
+`R::Async` / `R.eval_r_async` free the **Ruby** thread while the **same** bridge R process
+runs your code. That is enough for Rails-style “don’t block the request thread,” but not
+enough for heavy `install.packages` or multi-minute model fits: the gatekeeper R is still
+busy, other chunks time out, and abandoning the wait can leave compile work burning RAM.
+
+**`R::Job`** runs that work in a **child `Rscript` process**. The bridge stays free. Logs and
+metadata live under `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`).
+
+### Package installs
+
+`R.install_and_loads` / `R.install_rlibs` use `R::Job.install` and **await until the child
+finishes** (default: no wall-clock limit). Optional limit: `GALAAZ_INSTALL_TIMEOUT_SEC` or
+`install_timeout_sec:`. On timeout the child process group is killed so leftover
+`make`/`gcc` cannot OOM the shell. Stale `00LOCK-*` dirs are cleared before the next install.
+Only one install runs at a time (`install.lock`).
+
+```{ruby r_job_install_note, eval=FALSE}
+# May take a long time the first time (e.g. caret); the bridge is not used for compile.
+R.install_and_loads 'caret'
+```
+
+### Long arbitrary R (`eval` / `script`)
+
+Prefer the **block** form (like `File.open`): await the child, yield the job, return the
+block’s value. Without a block, the methods still await by default and return the `Job`.
+
+```{ruby r_job_eval_block}
+coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  fit <- lm(mpg ~ wt, data = mtcars)
+  saveRDS(unname(coef(fit)), result_path)
+R
+puts coef
+```
+
+```{ruby r_job_eval_no_block, eval=FALSE}
+# Without a block: awaits (wait: true is the default) and returns the Job
+job = R::Job.eval(code)
+job = R::Job.eval(code, wait: false)  # start only; call job.wait later
+
+# Script file; trailing args → commandArgs(trailingOnly=TRUE) in the child
+res = R::Job.script('train.R', '5') { |job| job.load_rds }
+```
+
+In the child: `setwd(job.dir)`, `.libPaths` includes the Galaaz user library,
+`GALAAZ_JOB_DIR` is set, and **`result_path`** defaults to
+`file.path(GALAAZ_JOB_DIR, "result.rds")`. Persist with `saveRDS(..., result_path)`, then
+load on the bridge with **`job.load_rds`** (short sync `readRDS` → a normal Galaaz R object).
+
+### Choosing async vs Job
+
+| Need | Use |
+|------|-----|
+| Don’t freeze a Ruby thread; short/medium R on the bridge is OK | `R::Async` / `R.eval_r_async` |
+| Install CRAN packages, or long R that must not block the bridge | `R::Job` / `R.install_and_loads` |
+
 ## Galaaz + Rails (R-on-Rails) integration baseline
 
 This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
@@ -1163,7 +1225,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}`r ''`

data/blogs/manual/manual.md

@@ -73,7 +73,7 @@ rewrite in another stack. **R-on-Rails** means:
 1. **Keep your science in R** — packages, formulas, plots, Bioconductor, the same engine as RStudio.
 2. **Learn enough Ruby/Rails** — routes, controllers, views, jobs, auth—not a second statistics career.
 3. **Call R from the app** — Galaaz loads R behind the scenes; long jobs can complete asynchronously
-   while Rails stays responsive (see later sections on the bridge and `R::Async`).
+   while Rails stays responsive (see later sections on the bridge, `R::Async`, and `R::Job`).
 4. **Ship alone when you need to** — one developer can own both the analysis and the product UI,
    without waiting for a separate “stats engineer” and “Rails engineer.”
 
@@ -456,8 +456,13 @@ driver). For concurrency tests on the bridge itself, see `specs/bridge_concurren
 
 ## Long-running R calls and a completion block
 
-For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by
-scheduling the call and resuming in a **block** when the `RET` arrives.
+For R work that can take a long time **on the bridge**, the bridge can avoid a Ruby-side
+**wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives.
+
+**Important distinction:** this keeps the **same** GNU R process busy. Other sync
+`eval_r` / gknit chunks still wait on that R. For CRAN installs and other work that must
+**not** monopolize the bridge (or that can OOM a small VM if abandoned mid-compile), use
+**`R::Job`** in the next section instead.
 
 - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value`
   is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit).
@@ -514,6 +519,67 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
+## Background R jobs (`R::Job`)
+
+`R::Async` / `R.eval_r_async` free the **Ruby** thread while the **same** bridge R process
+runs your code. That is enough for Rails-style “don’t block the request thread,” but not
+enough for heavy `install.packages` or multi-minute model fits: the gatekeeper R is still
+busy, other chunks time out, and abandoning the wait can leave compile work burning RAM.
+
+**`R::Job`** runs that work in a **child `Rscript` process**. The bridge stays free. Logs and
+metadata live under `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`).
+
+### Package installs
+
+`R.install_and_loads` / `R.install_rlibs` use `R::Job.install` and **await until the child
+finishes** (default: no wall-clock limit). Optional limit: `GALAAZ_INSTALL_TIMEOUT_SEC` or
+`install_timeout_sec:`. On timeout the child process group is killed so leftover
+`make`/`gcc` cannot OOM the shell. Stale `00LOCK-*` dirs are cleared before the next install.
+Only one install runs at a time (`install.lock`).
+
+``` ruby
+# May take a long time the first time (e.g. caret); the bridge is not used for compile.
+R.install_and_loads 'caret'
+```
+
+### Long arbitrary R (`eval` / `script`)
+
+Prefer the **block** form (like `File.open`): await the child, yield the job, return the
+block’s value. Without a block, the methods still await by default and return the `Job`.
+
+``` ruby
+coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  fit <- lm(mpg ~ wt, data = mtcars)
+  saveRDS(unname(coef(fit)), result_path)
+R
+puts coef
+```
+
+```
+## [1] 37.285126 -5.344472
+```
+
+``` ruby
+# Without a block: awaits (wait: true is the default) and returns the Job
+job = R::Job.eval(code)
+job = R::Job.eval(code, wait: false)  # start only; call job.wait later
+
+# Script file; trailing args → commandArgs(trailingOnly=TRUE) in the child
+res = R::Job.script('train.R', '5') { |job| job.load_rds }
+```
+
+In the child: `setwd(job.dir)`, `.libPaths` includes the Galaaz user library,
+`GALAAZ_JOB_DIR` is set, and **`result_path`** defaults to
+`file.path(GALAAZ_JOB_DIR, "result.rds")`. Persist with `saveRDS(..., result_path)`, then
+load on the bridge with **`job.load_rds`** (short sync `readRDS` → a normal Galaaz R object).
+
+### Choosing async vs Job
+
+| Need | Use |
+|------|-----|
+| Don’t freeze a Ruby thread; short/medium R on the bridge is OK | `R::Async` / `R.eval_r_async` |
+| Install CRAN packages, or long R that must not block the bridge | `R::Job` / `R.install_and_loads` |
+
 ## Galaaz + Rails (R-on-Rails) integration baseline
 
 This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
@@ -1873,7 +1939,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}

data/lib/R_interface/new_bridge_adapter.rb

@@ -24,7 +24,21 @@ module R
                     File.expand_path('../../ext/new_bridge/galaaz_gatekeeper_phase1.cpp', __dir__)
       @client = NewBridge::SessionClient.new(source_path: source_path)
       @client.start(accept_timeout: 120)
+      bootstrap_session!
+      @ready = true
+    end
 
+    # After a hung/timed-out R eval (e.g. install.packages), kill R and start a fresh runtime
+    # so the compile does not keep running and OOM the host shell.
+    def restart_runtime!(accept_timeout: 120)
+      @ready = false
+      @client.restart!(accept_timeout: accept_timeout)
+      bootstrap_session!
+      @ready = true
+      self
+    end
+
+    def bootstrap_session!
       # Compatibility with the legacy ShadowBridge setup:
       # - `R.awt` / X11 for plotting (examples/sthda_ggplot).
       # - `missing_arg()` for Ruby :all in `[` / tbl subset (R::Support.parse_arg).
@@ -117,7 +131,6 @@ module R
         parent_id: callback_parent_id,
         timeout: init_timeout
       )
-      @ready = true
     end
 
     def ready?

data/lib/R_interface/r.rb

@@ -30,6 +30,7 @@ dir = File.dirname(File.expand_path('.', __FILE__))
 
 # Bridge and Support first
 require_relative 'rsupport'
+require_relative 'r_job'
 
 # Operator modules next (so R::Object can include them)
 require_relative 'rbinary_operators'
@@ -134,68 +135,74 @@ module R
 
   def self.install_rlibs(*libs, install_timeout_sec: nil, callback_timeout_ms: nil, bridge_timeout_sec: nil)
     with_callback_timeout_ms(callback_timeout_ms) do
+      # Await wall-clock for the child Rscript job (nil = wait forever).
+      # Prefer install_timeout_sec / GALAAZ_INSTALL_TIMEOUT_SEC; bridge_timeout_sec
+      # is legacy and only used if the others are unset.
+      await_timeout = install_timeout_sec
+      if await_timeout.nil?
+        raw = ENV['GALAAZ_INSTALL_TIMEOUT_SEC']
+        unless raw.nil? || raw.to_s.strip.empty?
+          await_timeout = begin
+            Integer(raw)
+          rescue StandardError, ArgumentError
+            nil
+          end
+        end
+      end
+      await_timeout = bridge_timeout_sec if await_timeout.nil? && !bridge_timeout_sec.nil?
 
-      # Use a fixed local library directory and ensure R can see it
-      lib_dir = File.expand_path("~/R/x86_64-pc-linux-gnu-library/galaaz")
-      FileUtils.mkdir_p(lib_dir) unless Dir.exist?(lib_dir)
-      R.bridge.eval_r(".libPaths(c('#{lib_dir.gsub("'", "\\\\'")}', .libPaths()))", timeout: bridge_timeout_sec)
+      lib_dir = R::Job.default_lib_dir
+      FileUtils.mkdir_p(lib_dir)
+      R.bridge.eval_r(".libPaths(c('#{lib_dir.gsub("'", "\\\\'")}', .libPaths()))", timeout: 60)
 
       packages = R.c(*libs)
-
-    # installed.packages() returns a matrix; package names are in the row names.
-    # Using [:all, "Package"] on this matrix ends up calling [[ with a missing
-    # row subscript in R, which raises "missing subscript". Instead, rely on
-    # the row names vector for the list of installed packages.
-    installed_mat   = R.installed__packages(nil)
-    installed_names = R.rownames(installed_mat)
-
-    new_packages = packages[!(packages._ :in, installed_names)]
-    new_packages_str = new_packages.to_s
-
-      if(new_packages.length > 0 && new_packages_str != "character(0)")
-      $stderr.puts "[RUBY] The following packages are missing and will be installed: #{new_packages_str}"
-      $stderr.puts "[RUBY] Installing to: #{lib_dir}"
-      
-      # Get packages as Ruby array using :native mode
-      pkg_list = []
-      new_packages.each(:native) { |pkg| pkg_list << pkg }
-      $stderr.puts "[RUBY] Package list: #{pkg_list.inspect}"
-      
-      # Install each package
-      pkg_list.each do |pkg|
-        $stderr.puts "[RUBY] Installing #{pkg}..."
-        if install_timeout_sec
-          timeout_i = Integer(install_timeout_sec)
-          R.bridge.eval_r("options(timeout=#{timeout_i})", timeout: bridge_timeout_sec)
-        end
-        r_cmd = "install.packages('#{pkg.gsub("'", "\\\\'")}', repos='https://cloud.r-project.org', lib='#{lib_dir.gsub("'", "\\\\'")}', dependencies=NA)"
-        $stderr.puts "[RUBY] R command: #{r_cmd}"
-        result = R.bridge.eval_r(r_cmd, timeout: bridge_timeout_sec)
-        $stderr.puts "[RUBY] Install output: #{result.inspect}"
-        if result.to_s.include?("ANTICONF") || result.to_s.include?("Configuration failed")
-          $stderr.puts "[RUBY] WARNING: Package #{pkg} failed to install due to missing system libraries."
-          $stderr.puts "[RUBY] For kableExtra, you may need: libfontconfig1-dev libxml2-dev libfreetype6-dev"
+      installed_mat   = R.installed__packages(nil)
+      installed_names = R.rownames(installed_mat)
+      new_packages = packages[!(packages._ :in, installed_names)]
+      new_packages_str = new_packages.to_s
+
+      if new_packages.length > 0 && new_packages_str != 'character(0)'
+        pkg_list = []
+        new_packages.each(:native) { |pkg| pkg_list << pkg }
+        $stderr.puts "[RUBY] The following packages are missing and will be installed via R::Job: #{pkg_list.inspect}"
+        $stderr.puts "[RUBY] Installing to: #{lib_dir}"
+        $stderr.puts "[RUBY] Bridge R stays free; awaiting child Rscript" +
+                     (await_timeout ? " (timeout=#{await_timeout}s)" : ' (no await timeout)')
+
+        pkg_list.each do |pkg|
+          $stderr.puts "[RUBY] R::Job.install #{pkg}..."
+          begin
+            job = R::Job.install(pkg, lib_dir: lib_dir, wait: true, timeout: await_timeout)
+            job.raise_if_failed!
+            $stderr.puts "[RUBY] R::Job #{job.id} OK for #{pkg}"
+          rescue R::Job::Timeout => e
+            # Child Rscript process group already killed inside Job#wait.
+            raise "R package '#{pkg}' install job timed out. #{e.message}\n" \
+                  "Install outside gknit if needed, then re-run:\n" \
+                  "  Rscript -e \"install.packages('#{pkg}', lib='#{lib_dir}', repos='#{R::Job::DEFAULT_REPOS}')\""
+          rescue R::Job::Failed => e
+            raise "Failed to install R package '#{pkg}' via R::Job.\n#{e.message}"
+          end
         end
-      ensure
-        begin
-          R.bridge.eval_r("options(timeout=60)", timeout: bridge_timeout_sec)
-        rescue StandardError
-          nil
+
+        # Refresh bridge view of libraries after child install.
+        R.bridge.eval_r(".libPaths(c('#{lib_dir.gsub("'", "\\\\'")}', .libPaths()))", timeout: 60)
+        installed_mat = R.installed__packages(nil)
+        installed_names = R.rownames(installed_mat)
+        still_missing = packages[!(packages._ :in, installed_names)]
+        still_missing_str = still_missing.to_s
+        if still_missing.length > 0 && still_missing_str != 'character(0)'
+          raise "Failed to install packages: #{still_missing}. Check ~/.local/share/galaaz/jobs/*/job.log"
         end
       end
-      
-      # Re-check installed packages after install attempt
-      installed_mat = R.installed__packages(nil)
-      installed_names = R.rownames(installed_mat)
-      still_missing = packages[!(packages._ :in, installed_names)]
-      if still_missing.length > 0
-        raise "Failed to install packages: #{still_missing.to_s}. Check stderr output above for [RUBY] debug messages."
-      end
-      end
-
     end
   end
 
+  # Start a CRAN install Job without awaiting (advanced). Prefer +install_and_loads+.
+  def self.install_async(*libs, lib_dir: R::Job.default_lib_dir)
+    R::Job.install(*libs, lib_dir: lib_dir, wait: false)
+  end
+
   #----------------------------------------------------------------------------------------
   #
   #----------------------------------------------------------------------------------------