@zalom/plastic 1.9.0 → 1.10.0

package/scripts/lib/installer_core.rb

@@ -8,6 +8,7 @@ require "digest"
 require "time"
 require_relative "hook_registry"
 require_relative "agent_models"
+require_relative "harness_text"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -245,6 +246,7 @@ class InstallerCore
     FileUtils.mkdir_p(plastic_home)
     FileUtils.mkdir_p(File.join(plastic_home, "scripts", "lib"))
     FileUtils.mkdir_p(File.join(plastic_home, "templates"))
+    FileUtils.mkdir_p(File.join(plastic_home, "hooks"))
 
     core_files.each do |src, dest|
       src_path = File.join(package_root, src)
@@ -258,6 +260,14 @@ class InstallerCore
     File.write(File.join(plastic_home, "VERSION"), "#{version}\n")
 
     Dir.glob(File.join(plastic_home, "scripts", "*")).each { |f| FileUtils.chmod(0o755, f) if File.file?(f) }
+    # Same treatment for the hook launchers, and UNCONDITIONAL on update as well as install:
+    # FileUtils.cp onto an existing file keeps the DESTINATION's old mode, so a copy over a
+    # non-executable predecessor would stay non-executable forever and capture3 would raise
+    # EACCES into the same silent fail-open this intent is closing. *.json is skipped because
+    # hooks.json is a registry, not a program (same reasoning as test/rubyopt_clearing_test.rb).
+    Dir.glob(File.join(plastic_home, "hooks", "*")).each do |f|
+      FileUtils.chmod(0o755, f) if File.file?(f) && !f.end_with?(".json")
+    end
 
     global_files = core_files.values.map { |d| File.join(plastic_home, d) }
     global_files << File.join(plastic_home, "VERSION")
@@ -283,12 +293,30 @@ class InstallerCore
     end
   end
 
+  # Hook launchers ship in full: scripts/codex-hook resolves a live-state launcher at
+  # __dir__/../hooks/<gate>, which is ~/.plastic/hooks/<gate> once installed, so the launchers
+  # have to BE there or every Codex live-state hook fails open with no message (intent 249).
+  # Glob-derived for the same reason template_files is: a hand-written list hid two template
+  # files from every install for five weeks (intent 190), and a new hook must register itself.
+  # No path rewrite on this copy, unlike install_claude's: the launchers resolve their core
+  # through "$SCRIPT_DIR/../scripts/", which from ~/.plastic/hooks/ already lands on
+  # ~/.plastic/scripts/. Copied whole, hooks.json and run-hook and statusline included: all
+  # three are inert at that path, and an exclusion list is exactly the maintenance this avoids.
+  def hook_files
+    Dir.glob(File.join(package_root, "hooks", "*")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("hooks", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
   # by install_sync_test). The templates half is glob-derived (template_files above); the
   # rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files)
+    hand_registered_files.merge(template_files).merge(hook_files)
   end
 
   def hand_registered_files
@@ -308,6 +336,7 @@ class InstallerCore
       "scripts/hook-power-tools" => "scripts/hook-power-tools",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
+      "scripts/lib/ruby_probe.rb" => "scripts/lib/ruby_probe.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
       "scripts/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
@@ -357,6 +386,8 @@ class InstallerCore
       "scripts/lib/edit_gates.rb" => "scripts/lib/edit_gates.rb",
       "scripts/hook-edit-gates" => "scripts/hook-edit-gates",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
+      "scripts/lib/codex_edit_gates.rb" => "scripts/lib/codex_edit_gates.rb",
+      "scripts/lib/harness_text.rb" => "scripts/lib/harness_text.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
@@ -370,7 +401,17 @@ class InstallerCore
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
       "scripts/rollback.rb" => "scripts/rollback.rb",
       "scripts/lib/outcome_guard.rb" => "scripts/lib/outcome_guard.rb",
+      "scripts/lib/spec_header.rb" => "scripts/lib/spec_header.rb",
+      "scripts/lib/scaffold_intent.rb" => "scripts/lib/scaffold_intent.rb",
+      "scripts/scaffold-intent" => "scripts/scaffold-intent",
+      "scripts/lib/verify_intent.rb" => "scripts/lib/verify_intent.rb",
+      "scripts/verify-intent" => "scripts/verify-intent",
+      "scripts/lib/start_intent.rb" => "scripts/lib/start_intent.rb",
+      "scripts/start-intent" => "scripts/start-intent",
+      "scripts/lib/exec_worktree.rb" => "scripts/lib/exec_worktree.rb",
+      "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
+      "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
       "scripts/skill-lint" => "scripts/skill-lint",
       "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
@@ -760,7 +801,16 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
-    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    # Intent 239: Codex is the one harness that gets its instruction text projected at
+    # copy time. skill_names comes from the real skills/ listing, so the rewrite table
+    # maintains itself as skills are added and renamed. Every OTHER install path passes
+    # no transform and keeps the byte-for-byte copy.
+    skill_names = Dir.children(skills_source).select { |e| File.directory?(File.join(skills_source, e)) }
+    codex_transform = lambda do |content, rel|
+      HarnessText.for_codex(content, rel_path: rel, skill_names: skill_names)
+    end
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"),
+                                     exclude: skill_exclude, transform: codex_transform) if File.directory?(skills_source)
     # Codex-scoped overrides only (agents.models.codex.*): a literal Claude
     # model id set under agents.models.claude.* (or the legacy flat form,
     # which resolves as claude) must never reach a Codex TOML.
@@ -952,15 +1002,19 @@ class InstallerCore
   # instead, so every skill can read it from one shared location. `exclude` skips
   # named top-level skill directories entirely (intent 185: the agent-advisor skill
   # when advisor.enabled is false).
-  def install_skills_flat(skills_source, skills_root, exclude: [])
+  def install_skills_flat(skills_source, skills_root, exclude: [], transform: nil)
     installed = []
     FileUtils.mkdir_p(skills_root)
 
     Dir.children(skills_source).reject { |e| e.start_with?(".") || exclude.include?(e) }.each do |entry|
       src = File.join(skills_source, entry)
       if File.directory?(src)
-        installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"))
+        installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"),
+                                        transform: transform, rel_prefix: entry)
       elsif entry.start_with?("_") && entry.end_with?(".md")
+        # Spec D8: shared fragments land in the HARNESS-NEUTRAL plastic_home, shared
+        # with any co-installed Claude. Never transformed, or a Codex install would
+        # corrupt Claude's copy of the same file.
         FileUtils.mkdir_p(plastic_home)
         dest = File.join(plastic_home, entry)
         FileUtils.cp(src, dest)
@@ -1459,16 +1513,22 @@ class InstallerCore
     agents.find { |a| a[:key] == key }
   end
 
-  def copy_dir_recursive(src, dest)
+  def copy_dir_recursive(src, dest, transform: nil, rel_prefix: "")
     files = []
     FileUtils.mkdir_p(dest)
     Dir.entries(src).reject { |e| e.start_with?(".") }.each do |entry|
       src_path = File.join(src, entry)
       dest_path = File.join(dest, entry)
+      rel = rel_prefix.empty? ? entry : File.join(rel_prefix, entry)
       if File.directory?(src_path)
-        files += copy_dir_recursive(src_path, dest_path)
+        files += copy_dir_recursive(src_path, dest_path, transform: transform, rel_prefix: rel)
       elsif File.file?(src_path)
-        FileUtils.cp(src_path, dest_path)
+        if transform && File.extname(entry) == ".md"
+          File.write(dest_path, transform.call(File.read(src_path), rel))
+          File.chmod(File.stat(src_path).mode & 0o7777, dest_path)
+        else
+          FileUtils.cp(src_path, dest_path)
+        end
         files << dest_path
       end
     end

package/scripts/lib/lock.rb

@@ -56,6 +56,37 @@ module Lock
   # either way (takeover), so the TTL only bounds WHEN takeover is allowed.
   TTL_SECONDS = 1800
 
+  # The write guard is a mutex, not a lock in the Plastic sense: it carries no
+  # owner, no timestamp, and no content, it is only an inode to flock. It is
+  # a SIBLING of delivery.lock (never delivery.lock itself), because renaming
+  # over a file you hold an flock on leaves you holding an orphaned inode
+  # while the next writer flocks a fresh one at the same path. The name lands
+  # inside the existing *.lock rule in ~/.plastic/.gitignore, so no gitignore
+  # change is needed.
+  WRITE_GUARD_TIMEOUT_SECONDS = 2.0
+  WRITE_GUARD_RETRY_SECONDS = 0.01
+
+  # The sibling guard path for a lock type. NOT built by passing a compound
+  # type: into path (see TYPES comment above): Lock.path(dir, type:
+  # "delivery.write") would render the same string, and the exclusion at
+  # acquire ((TYPES - [type]).first) silently checks only one other type, so
+  # a third TYPES entry would break mutual exclusion with no error. This
+  # helper keeps the guard entirely outside TYPES.
+  def write_guard_path(intent_dir, type: "delivery")
+    File.join(intent_dir, "#{type}.write.lock")
+  end
+
+  # The sibling temp path for write's write-to-temp-then-rename. Ends in
+  # ".lock" (not just ".tmp") so a temp orphaned by a crash between the
+  # write and the rename is covered by the store's existing *.lock
+  # .gitignore rule rather than committed by the store's `git add -A`
+  # auto-commit. Sibling in the same directory as the target, never a
+  # system tmpdir, because File.rename can raise EXDEV across filesystems.
+  def write_temp_path(intent_dir, type: "delivery")
+    "#{path(intent_dir, type: type)}.tmp.#{Process.pid}.#{Thread.current.object_id}." \
+      "#{Time.now.to_f}.lock"
+  end
+
   def blank?(value)
     value.nil? || value.to_s.strip.empty?
   end
@@ -122,15 +153,30 @@ module Lock
     existing = read(intent_dir, type: type)
     if existing
       if existing["owner_session"].to_s == session.to_s
-        data = payload(session: session, type: type, host: host, now: now,
-                       delegates: Array(existing["delegates"]),
-                       delegate_activity: Array(existing["delegate_activity"]),
-                       harness: merged_value(harness, existing["owner_harness"]),
-                       agent: merged_value(agent, existing["owner_agent"]),
-                       model: merged_value(model, existing["owner_model"]),
-                       thread: merged_value(thread, existing["owner_thread"]),
-                       run_mode: merged_value(run_mode, existing["run_mode"]))
-        write(intent_dir, data, type: type)
+        # Re-read happens INSIDE the guard so the read-modify-write is
+        # covered, not just the write (spec D5). Fall back to the
+        # already-read existing when the file has vanished underneath us.
+        # If the re-read shows a different owner, keep today's outcome and
+        # write anyway: an owner-changed-underneath refusal would be new
+        # semantics the spec does not authorize. The rebuilt payload then
+        # carries THIS session as owner while inheriting the NEW owner's
+        # delegate list, merging two lock identities into one record. The
+        # window is a takeover landing between the pre-guard read and the
+        # guarded re-read; no test covers it, and closing it means guarding
+        # takeover itself, which this intent's scope does not authorize.
+        data = with_write_guard(intent_dir, type: type) do
+          record = read(intent_dir, type: type) || existing
+          rebuilt = payload(session: session, type: type, host: host, now: now,
+                            delegates: Array(record["delegates"]),
+                            delegate_activity: Array(record["delegate_activity"]),
+                            harness: merged_value(harness, record["owner_harness"]),
+                            agent: merged_value(agent, record["owner_agent"]),
+                            model: merged_value(model, record["owner_model"]),
+                            thread: merged_value(thread, record["owner_thread"]),
+                            run_mode: merged_value(run_mode, record["run_mode"]))
+          write(intent_dir, rebuilt, type: type)
+          rebuilt
+        end
         return [:owned, data]
       end
       return [:held, existing] if fresh?(intent_dir, type: type, ttl: ttl, now: now)
@@ -203,27 +249,32 @@ module Lock
   # lock. Only the OWNER may delegate; delegates cannot re-delegate.
   def add_delegate(intent_dir, delegate:, session:, type: "delivery", now: Time.now,
                    harness: nil, agent: nil, model: nil, thread: nil)
-    data = read(intent_dir, type: type)
     return false if blank?(delegate)
-    return false unless data && data["owner_session"].to_s == session.to_s
-    data["delegates"] = (Array(data["delegates"]) + [delegate.to_s]).uniq
-    activity = Array(data["delegate_activity"])
-    previous = activity.find { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
-    activity.reject! { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
-    record = {
-      "session" => delegate.to_s,
-      "status" => "active",
-      "registered_at" => now.utc.iso8601,
-      "last_activity_at" => now.utc.iso8601,
-      "harness" => merged_value(harness, previous && previous["harness"]),
-      "agent" => merged_value(agent, previous && previous["agent"]),
-      "model" => merged_value(model, previous && previous["model"]),
-      "thread" => merged_value(thread, previous && previous["thread"]),
-    }
-    data["delegate_activity"] = bounded_delegate_activity(activity + [record],
-                                                          delegates: data["delegates"])
-    write(intent_dir, data, type: type)
-    true
+    # The read moves inside the guard (spec D5): a guard around the write
+    # alone still loses updates, since both writers already read the stale
+    # copy before contending for the guard.
+    with_write_guard(intent_dir, type: type) do
+      data = read(intent_dir, type: type)
+      next false unless data && data["owner_session"].to_s == session.to_s
+      data["delegates"] = (Array(data["delegates"]) + [delegate.to_s]).uniq
+      activity = Array(data["delegate_activity"])
+      previous = activity.find { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
+      activity.reject! { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
+      record = {
+        "session" => delegate.to_s,
+        "status" => "active",
+        "registered_at" => now.utc.iso8601,
+        "last_activity_at" => now.utc.iso8601,
+        "harness" => merged_value(harness, previous && previous["harness"]),
+        "agent" => merged_value(agent, previous && previous["agent"]),
+        "model" => merged_value(model, previous && previous["model"]),
+        "thread" => merged_value(thread, previous && previous["thread"]),
+      }
+      data["delegate_activity"] = bounded_delegate_activity(activity + [record],
+                                                            delegates: data["delegates"])
+      write(intent_dir, data, type: type)
+      true
+    end
   end
 
   # Activity metadata is observational only. Finishing or failing a delegate
@@ -231,21 +282,23 @@ module Lock
   def update_delegate_status(intent_dir, delegate:, status:, session:, type: "delivery",
                              now: Time.now)
     return false unless (DELEGATE_STATUSES - ["active"]).include?(status.to_s)
-    data = read(intent_dir, type: type)
-    return false unless data && data["owner_session"].to_s == session.to_s
-    activity = Array(data["delegate_activity"])
-    index = activity.index do |record|
-      record.is_a?(Hash) && record["session"].to_s == delegate.to_s
+    with_write_guard(intent_dir, type: type) do
+      data = read(intent_dir, type: type)
+      next false unless data && data["owner_session"].to_s == session.to_s
+      activity = Array(data["delegate_activity"])
+      index = activity.index do |record|
+        record.is_a?(Hash) && record["session"].to_s == delegate.to_s
+      end
+      next false unless index
+      activity[index] = activity[index].merge(
+        "status" => status.to_s,
+        "last_activity_at" => now.utc.iso8601
+      )
+      data["delegate_activity"] = bounded_delegate_activity(activity,
+                                                            delegates: data["delegates"])
+      write(intent_dir, data, type: type)
+      true
     end
-    return false unless index
-    activity[index] = activity[index].merge(
-      "status" => status.to_s,
-      "last_activity_at" => now.utc.iso8601
-    )
-    data["delegate_activity"] = bounded_delegate_activity(activity,
-                                                          delegates: data["delegates"])
-    write(intent_dir, data, type: type)
-    true
   end
 
   # Owner releases the lock (disarm / End tail, D6). force: true is the repair
@@ -289,11 +342,107 @@ module Lock
     [:taken, data]
   end
 
-  # Rewrite the lock file in place (owner-side mutations). A content write also
-  # refreshes the mtime, which is correct: every sanctioned mutation is owner
-  # activity.
+  # Bounded mutual exclusion for the read-modify-write callers of write (spec
+  # D3, D5): acquire's re-acquire branch, add_delegate, and
+  # update_delegate_status each read, modify, then write, and the guard must
+  # span the whole sequence, not just the write, or two writers that already
+  # read the stale copy before contending still lose an update.
+  #
+  # NOT re-entrant: it opens a fresh file descriptor on every call, and flock
+  # is scoped to the open file description, so a nested acquisition from the
+  # same process would conflict with its own outer hold and burn the whole
+  # timeout budget on every single write. write must never take this guard
+  # itself; only the three read-modify-write call sites do.
+  #
+  # Fails open on every edge, per Plastic's fail-open doctrine (intent 93 D7,
+  # 111, 112): when the guard file cannot be opened, and when the flock
+  # cannot be won inside guard_timeout, the block still runs and its value is
+  # still returned. The write still happens, still atomically; the worst case
+  # on timeout is exactly today's possibly-lost update, never a torn file and
+  # never a hang.
+  #
+  # The guard file must never be deleted, by anyone, ever. Unlinking an
+  # flock target is the unlink-recreate race: a later opener would create a
+  # fresh inode and stop serializing against the current holder, breaking
+  # mutual exclusion exactly when contention is highest. scripts/write-config:59
+  # leaves config.yml.lock in place for the same reason. A leftover guard
+  # file is inert: nothing reads it, it stays zero bytes, and
+  # scripts/end-intent:558 keys its exit contract on Lock.path alone. This is
+  # a requirement, not a guarantee the code enforces: the curator stray-file
+  # rule (skills/conventions/references/maintenance-and-revisions.md:155)
+  # has no *.lock carve-out today, so a wrongful delete there degrades one
+  # write window to the pre-fix (unguarded) behavior, not a hard failure.
+  def with_write_guard(intent_dir, type: "delivery",
+                       guard_timeout: WRITE_GUARD_TIMEOUT_SECONDS,
+                       guard_retry: WRITE_GUARD_RETRY_SECONDS)
+    handle = begin
+      File.open(write_guard_path(intent_dir, type: type), File::CREAT | File::RDWR, 0o644)
+    rescue SystemCallError
+      nil
+    end
+    return yield unless handle
+
+    begin
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + guard_timeout
+      begin
+        until handle.flock(File::LOCK_EX | File::LOCK_NB)
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          sleep guard_retry
+        end
+      rescue SystemCallError
+        # File#flock RAISES (does not return false) for every errno except
+        # EWOULDBLOCK, so on a filesystem where flock is unsupported (NFS,
+        # SMB, some FUSE mounts) this loop raises instead of just failing to
+        # win the lock. An flock we cannot take must degrade to an
+        # unguarded but still atomic write, same as the File.open rescue
+        # above, or this method breaks its own fail-open promise.
+        nil
+      end
+      yield
+    ensure
+      begin
+        handle.flock(File::LOCK_UN)
+      rescue SystemCallError
+        nil
+      end
+      begin
+        handle.close
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+
+  # Rewrite the lock file in place (owner-side mutations): write-to-sibling-
+  # temp plus File.rename, never an in-place truncate. POSIX rename is an
+  # atomic replace, so a concurrent reader always observes either the
+  # complete previous content or the complete new content, never a partial
+  # file. The temp file is a SIBLING in the same directory as the target,
+  # never a system tmpdir, because File.rename can raise EXDEV when the temp
+  # and the target live on different filesystems.
+  #
+  # A content write also refreshes the mtime, which is correct: every
+  # sanctioned mutation is owner activity. File.rename carries the temp
+  # file's mtime onto the target, so the post-rename mtime is "now", exactly
+  # what fresh? (above) and the hook heartbeats already assume. The rename
+  # also swaps the inode, which is safe here: heartbeat touches by path
+  # through FileUtils.touch, not by handle, and nothing in the repo holds an
+  # open handle on delivery.lock across a write.
+  #
+  # This method does NOT take the write guard itself. with_write_guard is not
+  # re-entrant, so a nested acquisition from the same process would conflict
+  # with its own outer hold and burn the entire timeout budget on every
+  # write, including the hot heartbeat path. The three read-modify-write
+  # callers take the guard around the whole sequence instead; write stays a
+  # bare atomic replace.
   def write(intent_dir, data, type: "delivery")
-    File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
+    target = path(intent_dir, type: type)
+    temp = write_temp_path(intent_dir, type: type)
+    File.write(temp, JSON.pretty_generate(data))
+    File.rename(temp, target)
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
   end
 
   # Read-only normalized inspection. The lock file and its mtime remain the

package/scripts/lib/ruby_probe.rb

@@ -0,0 +1,60 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Which ruby would a spawned Plastic hook actually get, and what version is it?
+# Intent 235, D6. Pure and dependency injected: the capture seam is a lambda, so
+# tests never spawn a process and never touch ENV.
+#
+# A hook is launched by the agent application, not by a login shell, so a version
+# manager that activates on shell prompt render (mise, rbenv, asdf) may never reach
+# it and bare `ruby` can still resolve to the system interpreter. Doctor reports
+# that. It never repairs it.
+#
+# Mechanism, and why it is honest:
+#   - The command word is the bare name "ruby", so the operating system resolves it
+#     on the inherited PATH exactly the way it does for a spawned bash launcher. We
+#     do not read PATH ourselves and we do not reimplement the search.
+#   - The resolved interpreter answers for itself: RUBY_VERSION is its own version,
+#     RbConfig.ruby is its own absolute path. One spawn, no guessing.
+#   - RUBYOPT is cleared, matching what every Plastic launcher now does. That makes
+#     this the honest simulation of the post-fix world, and it stops the probe from
+#     crashing on the exact machine that most needs the report (an old ruby plus a
+#     shell that exports RUBYOPT=--yjit).
+module RubyProbe
+  module_function
+
+  # A hash passed as the first argument MERGES onto the inherited environment. It
+  # clears nothing unless the key is present with a nil or empty value, so the nil
+  # here is load bearing.
+  CLEARED_ENV = { "RUBYOPT" => nil }.freeze
+
+  PROBE_ARGS = ["-rrbconfig", "-e", "puts RUBY_VERSION; puts RbConfig.ruby"].freeze
+
+  def default_capture
+    lambda do |env, command, *args|
+      require "open3"
+      out, _err, status = Open3.capture3(env, command, *args)
+      [out, status.success?]
+    rescue Errno::ENOENT
+      ["", false] # no ruby on PATH: undetectable, fail open
+    end
+  end
+
+  # => { found: true, version: "3.3.5", path: "/opt/ruby/bin/ruby" }
+  # => { found: false, version: nil, path: nil } on any trouble at all.
+  def resolve(capture: default_capture)
+    out, ok = capture.call(CLEARED_ENV, "ruby", *PROBE_ARGS)
+    return not_found unless ok
+
+    version, path = out.to_s.lines.map(&:strip).reject(&:empty?)
+    return not_found if version.nil? || version.empty?
+
+    { found: true, version: version, path: path }
+  rescue StandardError
+    not_found
+  end
+
+  def not_found
+    { found: false, version: nil, path: nil }
+  end
+end