rubik 0.1.0

data/lib/rubik/sandbox/driver/process.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../shell_resolver"
+require_relative "../../security/guard" unless defined?(Rubik::Security::Guard)
+require "open3"
+require "timeout"
+
+module Rubik
+  module Sandbox
+    module Driver
+      class ProcessDriver < Base
+        def available?
+          true
+        end
+
+        def run(cmd, timeout: 15, chdir: Dir.pwd, allow_network: false, memory_limit_mb: 512, cpus: "1.0") # rubocop:disable Lint/UnusedMethodArgument -- sürücü arayüzü kwarg'leri korunuyor
+          start_time = Time.now
+          stdout_str = ""
+          stderr_str = ""
+          exit_code = 127
+
+          # Explicit-argv spawn (Plan 55 D-1): never leave interpreter choice
+          # to Open3's string form — on Windows that silently means cmd.exe.
+          resolved = ShellResolver.resolve(cmd, preference: @options[:shell] || "auto")
+
+          env = {}
+          # Direct host execution does NOT inject misleading dead proxy variables (127.0.0.1:9999).
+          # Hardware/namespace network isolation is only provided when a true sandbox
+          # (Bubblewrap, Docker, Podman) is enabled.
+
+          pid = nil
+          begin
+            Timeout.timeout(timeout) do
+              Open3.popen3(env, *spawn_args_for(resolved, cmd), chdir: chdir) do |stdin, stdout, stderr, wait_thr|
+                pid = wait_thr.pid
+                begin
+                  stdin.close
+                rescue
+                  nil
+                end
+                t_out = Thread.new do
+                  stdout.read
+                rescue
+                  ""
+                end
+                t_err = Thread.new do
+                  stderr.read
+                rescue
+                  ""
+                end
+                begin
+                  stdout_str = t_out.value.to_s
+                  stderr_str = t_err.value.to_s
+                  status = wait_thr.value
+                  exit_code = status.exitstatus || (status.signaled? ? (128 + (status.termsig || 1)) : 1)
+                ensure
+                  begin
+                    t_out.kill
+                  rescue
+                    nil
+                  end
+                  begin
+                    t_err.kill
+                  rescue
+                    nil
+                  end
+                end
+              end
+            end
+          rescue Timeout::Error
+            Rubik::Platform.kill_tree(pid) if pid
+            stderr_str = "Execution timed out after #{timeout} seconds"
+            exit_code = 124
+          rescue StandardError => e
+            stderr_str = "Execution error: #{e.message}"
+            exit_code = 1
+          end
+
+          duration = Time.now - start_time
+          stderr_out = resolved[:note] ? "#{resolved[:note]}\n#{stderr_str}" : stderr_str
+          require_relative "../../security/redactor" unless defined?(Rubik::Security::Redactor)
+          clean_stdout = Rubik::Security::Redactor.redact(stdout_str)
+          clean_stderr = Rubik::Security::Redactor.redact(stderr_out)
+          {
+            ok: exit_code.zero?,
+            exit_code: exit_code,
+            stdout: clean_stdout,
+            stderr: clean_stderr,
+            output: [clean_stdout, clean_stderr].reject(&:empty?).join("\n"),
+            duration: duration.round(4),
+            driver: "process",
+            shell: resolved[:shell]
+          }
+        end
+
+        private
+
+        # cmd.exe parses its tail with its own quoting rules that standard
+        # Windows argv quoting cannot express, so the command must reach it
+        # as a bare string (Ruby's string spawn form routes exactly there).
+        # bash/sh/pwsh take clean argv arrays.
+        #
+        # DEFENSE-IN-DEPTH (this closure, not a residual gap): the classifier
+        # runs in the ProcessDriver guard (lib/rubik/security/guard) and gates
+        # every spawn BEFORE this method is called, so a dangerous command
+        # never reaches spawn. But the classifier in the guard classifies the
+        # RAW `cmd` string with POSIX Shellwords and a nil shell. When the
+        # resolved shell is "cmd" cmd.exe re-parses the tail with its own
+        # grammar, so a command the classifier deemed "safe" under POSIX could
+        # be re-interpreted (e.g. the cmd builtin `start http://x && evil.exe`
+        # — `start` opens a URL, then `&&` chains the second program). To close
+        # that split we (1) re-run the guard's classification with the cmd shell
+        # hint right here, BEFORE spawning, and (2) explicitly block the cmd.exe
+        # builtins and drive-letter destructive constructs that the POSIX
+        # classifier can misread as safe. A POSIX-safe command that is
+        # dangerous under cmd.exe is therefore rejected and never spawned.
+        def spawn_args_for(resolved, cmd)
+          resolved[:shell] == "cmd" ? verify_cmd_safe(cmd) : resolved[:argv]
+        end
+
+        # Guard the cmd.exe branch. Re-classifies with shell: "cmd" so the guard
+        # applies cmd.exe semantics (builtins, quoting) rather than POSIX ones,
+        # and explicitly blocks the builtins/drive constructs the POSIX
+        # classifier can misread as safe. A command POSIX-safe but
+        # cmd.exe-dangerous must NOT be spawned.
+        def verify_cmd_safe(cmd)
+          # SAFETY ORDER (critical): the global classifier/allowlist/fatal-regex
+          # check MUST run BEFORE any cmd-specific approval. verify_command_safety!
+          # gates every spawn on the operator allowlist and the catastrophic
+          # fallback regex, so nothing the classifier rejects can ever reach the
+          # spawn path — even though the cmd-specific check below could approve
+          # it. Reversing this order would let a cmd-specific construct bypass
+          # the allowlist (HIGH finding). verify_cmd_specific_safe! is only a
+          # late-stage refinement: it may tighten an already-approved command,
+          # never authorize one the classifier rejected.
+          verify_command_safety!(cmd, shell: "cmd")
+          verify_cmd_specific_safe!(cmd)
+          [cmd]
+        end
+
+        # cmd.exe builtins / constructs that POSIX Shellwords would treat as a
+        # harmless word or redirect but cmd.exe executes with special (often
+        # dangerous) meaning. Guarded behind windows? so non-Windows hosts (where
+        # a cmd branch never resolves) are unaffected.
+        CMD_DANGEROUS_CONSTRUCTS = [
+          /(?:\A|[&|;])\s*(?:start|call|goto)\b/i, # launch / subroutine / jump builtins
+          /\b(?:del|erase|rmdir)\b\s+.*[a-z]:\\/i, # drive-letter file removal
+          />\s*[a-z]:\\/i # output redirect to a drive-letter path (overwrite)
+        ].freeze
+        private_constant :CMD_DANGEROUS_CONSTRUCTS
+
+        def verify_cmd_specific_safe!(cmd)
+          return unless Rubik::Platform.windows?
+          return unless CMD_DANGEROUS_CONSTRUCTS.any? { |p| cmd.to_s.match?(p) }
+
+          raise_dangerous(cmd.to_s, rule_name: "cmd.exe_construct")
+        end
+
+        # Security guard gating cmd.exe spawns. The Runner injects the shared
+        # session guard via driver_opts (options[:guard]) so operator policy —
+        # the live command allowlist above all — applies here too; the lazy
+        # local fallback (silent audit, zero policy) serves only standalone /
+        # test-constructed drivers.
+        def guard
+          @options[:guard] || (@guard ||= Rubik::Security::Guard.new(audit_log_path: nil))
+        end
+
+        # Re-run the security guard's classification, scoped to the given shell
+        # so cmd.exe semantics are enforced when spawned via cmd. Blocks a
+        # POSIX-safe-but-cmd-dangerous command with BlockedWriteError.
+        def verify_command_safety!(cmd, shell: nil)
+          guard.verify_command_safety!(cmd, shell: shell)
+          true
+        end
+
+        # Raise the standard BlockedWriteError used throughout the guard
+        # surface for an explicitly detected dangerous construct.
+        def raise_dangerous(cmd, rule_name:)
+          raise Rubik::Security::BlockedWriteError.new(
+            "Dangerous command execution blocked: #{cmd}",
+            kind: :cmd_construct,
+            blocked_command: cmd,
+            rule_name: rule_name
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubik/sandbox/driver.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "driver/base"
+require_relative "driver/process"
+require_relative "driver/docker"
+require_relative "driver/podman"
+require_relative "driver/bubblewrap"
+
+module Rubik
+  module Sandbox
+    module Driver
+      @drivers = {}
+      @mutex = Monitor.new
+
+      def self.register(name, driver_class, ctx: nil)
+        key = name.to_s.downcase
+        restore = @mutex.synchronize do
+          prior = @drivers[key] # snapshot BEFORE the overwrite
+          @drivers[key] = driver_class
+          lambda do
+            # Revertible-by-construction: restore only if the slot still
+            # holds OUR class — a newer registration (re-registration,
+            # another plugin) owns the slot now and must survive this
+            # context's disposal. Disposing an overlay must not punch a
+            # hole through the built-in underneath it (AGENTS.md sound
+            # rollback).
+            @mutex.synchronize do
+              next unless @drivers.key?(key) && @drivers[key].equal?(driver_class)
+
+              prior ? @drivers[key] = prior : @drivers.delete(key)
+            end
+          end
+        end
+        ctx&.on_dispose(&restore)
+        driver_class
+      end
+
+      def self.unregister(name)
+        key = name.to_s.downcase
+        @mutex.synchronize { @drivers.delete(key) }
+      end
+
+      def self.registered_drivers
+        @mutex.synchronize { @drivers.dup }
+      end
+
+      def self.resolve(name, options = {})
+        return nil if name.nil?
+
+        key = name.to_s.downcase
+        return nil if ["process", "none"].include?(key)
+
+        driver_class = @mutex.synchronize { @drivers[key] }
+        return nil unless driver_class
+
+        driver_class.new(options)
+      end
+
+      def self.best_available(preferred = "auto", options = {})
+        pref = preferred.to_s.downcase
+        if pref != "auto" && !pref.empty?
+          return nil if ["process", "none"].include?(pref)
+
+          candidate = resolve(pref, options)
+          return candidate if candidate&.available?
+
+          return nil
+        end
+
+        if Rubik::Platform.linux?
+          bwrap = resolve("bwrap", options)
+          return bwrap if bwrap&.available?
+        end
+
+        docker = resolve("docker", options)
+        return docker if docker&.available?
+
+        podman = resolve("podman", options)
+        return podman if podman&.available?
+
+        nil
+      end
+
+      register("bwrap", BubblewrapDriver)
+      register("bubblewrap", BubblewrapDriver)
+      register("docker", DockerDriver)
+      register("podman", PodmanDriver)
+    end
+  end
+end

data/lib/rubik/sandbox/runner.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative "driver"
+require_relative "driver/process"
+require_relative "../security/errors"
+require_relative "../platform"
+
+module Rubik
+  module Sandbox
+    class Runner
+      attr_reader :root_dir, :driver, :allowed_external_dirs, :config, :guard
+
+      def initialize(root_dir: Dir.pwd, allow_network: false, driver: nil, config: nil, allowed_external_dirs: [], guard: nil)
+        @root_dir = File.expand_path(root_dir)
+        @config = config
+        @preferred_driver = driver
+        # Shared session guard (Composition provides it). Injected into every
+        # driver_opts rebuild below so reconfigure! cycles never strand a
+        # policy-less driver — the ProcessDriver consults it on cmd.exe
+        # re-verification, where an empty-allowlist guard would silently
+        # re-block commands the operator allowlisted.
+        @guard = guard
+        @allow_network = allow_network || @config&.fetch("sandbox.allow_network", false) || false
+        @allowed_external_dirs = (
+          Array(allowed_external_dirs) +
+          Array(@config&.fetch("workspace.allowed_external_dirs", []))
+        ).map { |d| File.expand_path(d.to_s, @root_dir) }.uniq
+        # Baseline captured BEFORE the first reconfigure: entries from
+        # construction arguments plus the config's current value. Dirs added
+        # later via add_allowed_dir (runtime-only) survive reconfigurations.
+        @baseline_allowed_dirs = @allowed_external_dirs.dup
+
+        reconfigure!
+
+        return unless @config.respond_to?(:on_change)
+
+        @config.on_change("sandbox") { reconfigure! }
+        # Track explicit edits to the allow-list key itself. Once the user
+        # has set this key at any scope, the config becomes authoritative:
+        # reconfigure! recomputes config-sourced entries from scratch so
+        # REMOVING a dir actually shrinks the live allow-list (the previous
+        # union-based merge was monotonic and left stale dirs allowed).
+        @config.on_change("workspace.allowed_external_dirs") do
+          @allowed_dirs_config_touched = true
+          reconfigure!
+        end
+      end
+
+      def sandbox_enabled?
+        return true if @preferred_driver && !@preferred_driver.is_a?(String) && !@preferred_driver.is_a?(Symbol)
+        return false if @config&.fetch("sandbox.driver", nil).to_s.downcase.then { |d| ["process", "none"].include?(d) }
+        return false if @preferred_driver.to_s.downcase.then { |d| ["process", "none"].include?(d) }
+
+        val = @config&.fetch("sandbox.enabled", false)
+        val == true || val.to_s.downcase == "true"
+      end
+
+      def reconfigure!
+        @allow_network = @config.fetch("sandbox.allow_network", @allow_network) if @config
+        if @config && @allowed_dirs_config_touched
+          # Config authoritative (user has edited the key at some scope):
+          # recompute config-sourced entries from scratch so REMOVING a dir
+          # shrinks the live allow-list. Runtime-only additions made through
+          # add_allowed_dir (absent from the baseline and the config) are
+          # preserved; explicit remove_allowed_dir deletions stay deleted
+          # because they are absent from both inputs.
+          #
+          # A malformed (non-Array) value must fail CLOSED: treating it as an
+          # empty config list and warning, rather than silently keeping the
+          # previously-merged union (which would leave stale dirs allowed).
+          raw_allowed = @config.fetch("workspace.allowed_external_dirs", [])
+          unless raw_allowed.is_a?(Array)
+            warn "[SANDBOX] workspace.allowed_external_dirs must be an Array (got #{raw_allowed.class}); " \
+                 "treating as empty — the config is authoritative, so stale dirs are revoked."
+            raw_allowed = []
+          end
+          baseline = @baseline_allowed_dirs || []
+          config_allowed = raw_allowed.map { |d| File.expand_path(d.to_s, @root_dir) }
+          runtime_added = (@allowed_external_dirs - baseline) - config_allowed
+          @allowed_external_dirs = (config_allowed + runtime_added).uniq
+        end
+        # Key untouched: construction baseline + runtime mutations stand —
+        # an unrelated sandbox key (enabled, timeout…, 15) must not wipe dirs.
+
+        @sandbox_enabled = sandbox_enabled?
+
+        driver_opts = {
+          image: @config&.fetch("sandbox.image", "rubik-sandbox:latest"),
+          shell: @config&.fetch("sandbox.shell", "auto") || "auto",
+          allowed_dirs: allowed_paths,
+          guard: @guard
+        }
+
+        @host_driver = Driver::ProcessDriver.new(driver_opts)
+
+        @driver = if @preferred_driver && !@preferred_driver.is_a?(String) && !@preferred_driver.is_a?(Symbol)
+                    @preferred_driver
+                  elsif @sandbox_enabled
+                    driver_to_use = @preferred_driver || @config&.fetch("sandbox.driver", nil) || "auto"
+                    Driver.best_available(driver_to_use, driver_opts)
+                  end
+      end
+
+      def allowed_paths
+        roots = [@root_dir]
+        if @config
+          extra_roots = Array(@config.fetch("workspace.additional_roots", [])).map { |r| File.expand_path(r.to_s, @root_dir) }
+          roots.concat(extra_roots)
+        end
+        roots.concat(@allowed_external_dirs)
+        roots.uniq
+      end
+
+      def add_allowed_dir(path)
+        expanded = File.expand_path(path.to_s, @root_dir)
+        @allowed_external_dirs << expanded unless @allowed_external_dirs.include?(expanded)
+        expanded
+      end
+
+      def remove_allowed_dir(path)
+        expanded = File.expand_path(path.to_s, @root_dir)
+        @allowed_external_dirs.delete(expanded)
+        expanded
+      end
+
+      def verify_chdir_safety!(chdir)
+        expanded = File.expand_path(chdir.to_s, @root_dir)
+        safe = allowed_paths.any? do |allowed|
+          Rubik::Platform.path_under?(expanded, allowed)
+        end
+
+        unless safe
+          raise Rubik::Security::BlockedWriteError.new(
+            "Execution blocked: chdir directory '#{chdir}' (#{expanded}) is outside of allowed workspace roots and external dirs.",
+            kind: :chdir_outside_root,
+            path: expanded
+          )
+        end
+
+        true
+      end
+
+      def allow_network?
+        if @config
+          cfg_val = @config.fetch("sandbox.allow_network", nil)
+          return true if cfg_val == true || cfg_val.to_s.downcase == "true"
+          return false if cfg_val == false || cfg_val.to_s.downcase == "false"
+
+          unless cfg_val.nil?
+            warn "[SANDBOX] Unparseable sandbox.allow_network value '#{cfg_val}'; defaulting to fail-closed (false)"
+            return false
+          end
+        end
+        @allow_network == true || @allow_network.to_s.downcase == "true"
+      end
+
+      def allow_network
+        allow_network?
+      end
+
+      def run(cmd, timeout: nil, chdir: @root_dir)
+        chdir_path = File.expand_path(chdir.to_s, @root_dir)
+        verify_chdir_safety!(chdir_path)
+
+        parsed_timeout = timeout&.to_i
+        effective_timeout = (parsed_timeout&.positive? ? parsed_timeout : nil) ||
+                            (@config && @config.fetch("sandbox.timeout_seconds", 15).to_i) || 15
+        effective_timeout = 15 if effective_timeout <= 0
+        mem_limit = @config&.fetch("sandbox.memory_limit_mb", 512) || 512
+        cpus = @config&.fetch("sandbox.cpus", "1.0") || "1.0"
+
+        active_driver = if sandbox_enabled? && @driver
+                          @driver
+                        else
+                          @host_driver || Driver::ProcessDriver.new(shell: @config&.fetch("sandbox.shell", "auto") || "auto",
+                                                                    guard: @guard)
+                        end
+
+        res = active_driver.run(
+          cmd,
+          timeout: effective_timeout,
+          chdir: chdir_path,
+          allow_network: allow_network?,
+          memory_limit_mb: mem_limit,
+          cpus: cpus
+        )
+
+        if res.is_a?(Hash)
+          res = res.dup if res.frozen?
+          # Session review B7: the per-run isolation line confused more than
+          # it informed once operators settled their setup — `sandbox.isolation_note`
+          # (default true, the historical behavior) can silence it.
+          res[:isolation] = isolation_disclosure if disclose_isolation?
+        end
+        res
+      end
+
+      def disclose_isolation?
+        @config.respond_to?(:fetch) ? @config.fetch("sandbox.isolation_note", true) != false : true
+      end
+
+      def isolation_disclosure
+        if sandbox_enabled? && @driver
+          net_status = allow_network? ? "allowed" : "none"
+          "🔍 Isolation: sandbox (#{@driver.name}, network=#{net_status}) — strong"
+        else
+          "🔍 Execution: direct (safe execution guardrails active; sandbox disabled)"
+        end
+      end
+
+      def isolation_level
+        return "sandbox (#{@driver.name})" if sandbox_enabled? && @driver
+
+        "direct (safe host)"
+      end
+    end
+  end
+end

data/lib/rubik/sandbox/shell_resolver.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  module Sandbox
+    # Decides which shell executes a run_command string and how (Plan 55).
+    # Single source of truth for shell identity: the process driver spawns
+    # through it, and the system prompt's <environment> line is generated
+    # from it. Pure functions only — no global state, no process spawns.
+    #
+    # Auto-routing is syntax-gated, drifting toward bash on doubt: a
+    # false positive (plain command under bash) is harmless because bash is
+    # a superset of cmd for our purposes, while a false negative (POSIX
+    # syntax under cmd) silently corrupts results.
+    module ShellResolver
+      SHELLS = ["auto", "bash", "pwsh", "cmd", "sh"].freeze
+      POWERSHELL = "pwsh"
+
+      # Syntax cmd.exe (and pwsh) cannot execute correctly.
+      BASH_REQUIRED = %r{<\(|>\(|/dev/null|<<[-~]?["']?[A-Za-z]|<<<}
+      # PowerShell-idiomatic tokens: $env: plus any Verb-Noun cmdlet shape
+      # (Select-String, Sort-Object, ConvertTo-Json, Out-File, ...). Live
+      # feedback (Plan 55 §9): models reach for Select-String as readily as
+      # Get-*, so the shape must be generic, not a Get-* prefix.
+      PS_FINGERPRINT = /\$env:|\b[A-Z][a-z]+(?:[A-Z][a-z]+)*-[A-Z][A-Za-z]+\b/
+      # Shell substitution/variables cmd.exe silently mangles. Paired single
+      # quotes are POSIX quoting: cmd.exe passes them through literally,
+      # which breaks tools like `gh --jq '...'` (Plan 55 §9, live feedback).
+      SUBSTITUTION = /\$\(|`|\$[A-Za-z_]|'[^']*'/
+
+      # Windows ships a WSL launcher as System32\bash.exe. It must never be
+      # auto-selected for repo commands: without a distro it just errors,
+      # and with one it would run Linux git against a Linux filesystem view.
+      WSL_STUB = %r{/system32/bash\.exe$}i
+      # Session review B7: bare `dir`/`where` are cmd.exe builtins with NO
+      # binary — under a bash-resolved spawn (POSIX quoting elsewhere in the
+      # command pulled it to bash) they died with ENOENT and the diagnostic
+      # engine filed them as MISSING_BINARY. Non-destructive listing/
+      # display builtins only: assoc/ftype mutate file-association state and
+      # the destructive ones (del, rd, start, call, ...) stay on their
+      # existing guard-verified paths untouched.
+      CMD_BUILTINS = ["dir", "where", "cls", "ver", "vol", "title", "prompt"].freeze
+      GIT_BASH_CANDIDATES = [
+        "C:/Program Files/Git/bin/bash.exe",
+        "C:/Program Files/Git/usr/bin/bash.exe",
+        "C:/Program Files (x86)/Git/bin/bash.exe"
+      ].freeze
+
+      module_function
+
+      # Returns { argv:, shell:, note: }. argv is spawned verbatim via
+      # Open3's array form; note (rare) explains a fallback and is meant to
+      # be prepended to the command's stderr. On Windows a resolved bash is
+      # always spawned by full path so PATH can never substitute the WSL
+      # launcher between resolution and spawn.
+      def resolve(cmd, platform: Rubik::Platform.os_family, preference: "auto", git_bash_candidates: GIT_BASH_CANDIDATES)
+        pref = normalize(preference)
+        chosen = pref == "auto" ? gate(cmd, platform) : pref
+
+        note = nil
+        unless available?(chosen, git_bash_candidates, platform: platform)
+          note = "Shell '#{chosen}' not found; falling back to #{default_shell(platform)}"
+          note += " (shell-specific syntax in this command may fail)" if chosen != default_shell(platform)
+          chosen = default_shell(platform)
+        end
+
+        argv = argv_for(chosen, cmd)
+        argv = [bash_path(git_bash_candidates, platform: platform), "-c", cmd] if chosen == "bash" && platform == :windows
+
+        { argv: argv, shell: chosen, note: note }
+      end
+
+      def default_shell(platform)
+        return "cmd" if platform == :windows
+
+        available?("bash", platform: platform) ? "bash" : "sh"
+      end
+
+      # One-line machine-readable shell facts for the system prompt.
+      def environment_line(preference = "auto", platform: Rubik::Platform.os_family)
+        pref = normalize(preference)
+        shell_desc = if pref != "auto"
+                       pref
+                     elsif platform == :windows
+                       "cmd (plain commands) | bash (POSIX quoting/syntax: '...', <(...), $(...), /dev/null) | " \
+                         "pwsh (PowerShell cmdlets) — auto-routed per command; escape hatch: bash -c '...'"
+                     else
+                       default_shell(platform)
+                     end
+        %(<environment os="#{platform}" shell="#{shell_desc}" />)
+      end
+
+      def argv_for(shell, cmd)
+        case shell
+        when "bash", "sh" then [shell, "-c", cmd]
+        when POWERSHELL then [POWERSHELL, "-NoProfile", "-NonInteractive", "-Command", cmd]
+        when "cmd" then ["cmd", "/c", cmd]
+        else [cmd]
+        end
+      end
+
+      def available?(shell, git_bash_candidates = GIT_BASH_CANDIDATES, platform: Rubik::Platform.os_family)
+        if platform == :windows
+          return !bash_path(git_bash_candidates, platform: platform).nil? if shell == "bash"
+          return true if shell == "cmd"
+
+          if shell == "pwsh"
+            pwsh_found = Rubik::Platform.which("pwsh") || Rubik::Platform.which("powershell")
+            return true if pwsh_found
+            return false if Rubik::Platform.windows?
+
+            # Simulated :windows platform on non-windows test hosts:
+            # If bash/cmd are stubbed to Windows paths but pwsh is nil, respect the missing stub
+            b_hit = Rubik::Platform.which("bash")
+            c_hit = Rubik::Platform.which("cmd")
+            win_stubbed = (b_hit && b_hit =~ %r{\A[a-zA-Z]:/}) || (c_hit && c_hit =~ %r{\A[a-zA-Z]:/})
+            return false if win_stubbed
+
+            return true
+          end
+        end
+
+        !Rubik::Platform.which(shell).nil?
+      end
+
+      # Usable bash on Windows: the PATH hit unless it is the WSL launcher,
+      # else bash derived from the installed git.exe (covers non-standard
+      # install roots like C:/Git or scoop), else the static Git for
+      # Windows paths. Nil means "no usable bash".
+      def bash_path(git_candidates = GIT_BASH_CANDIDATES, platform: Rubik::Platform.os_family)
+        candidate = Rubik::Platform.which("bash")
+        return candidate if candidate && !candidate.match?(WSL_STUB) && (platform != :windows || candidate.end_with?(".exe") || candidate.include?("/"))
+
+        git_exe = Rubik::Platform.which("git")
+        if git_exe
+          root = git_install_root(git_exe)
+          ["#{root}/bin/bash.exe", "#{root}/usr/bin/bash.exe", "#{root}/mingw64/bin/bash.exe"].each do |p|
+            return p if File.file?(p)
+          end
+        end
+        git_candidates.find { |p| File.file?(p) }
+      end
+
+      # C:/Git/cmd/git.exe -> C:/Git; C:/Git/mingw64/bin/git.exe -> C:/Git
+      # (lazy match + mingw64/bin first: bash lives at the INSTALL root's
+      # bin|usr/bin, not under mingw64)
+      def git_install_root(git_exe)
+        m = git_exe.match(%r{\A(.+?)/(?:mingw64/bin|usr/bin|cmd|bin)/git\.exe\z}i)
+        m ? m[1] : File.dirname(git_exe)
+      end
+
+      def normalize(preference)
+        pref = preference.to_s.downcase
+        SHELLS.include?(pref) ? pref : "auto"
+      end
+
+      def gate(cmd, platform)
+        # BASH_REQUIRED outranks the builtin route (review B7): `where git
+        # 2>/dev/null` must stay an honest bash run — cmd would mangle the
+        # POSIX redirect into a bogus drive path. CMD_BUILTINS still precede
+        # SUBSTITUTION so plain `dir 'some filter'` quoting reaches cmd.
+        return "bash" if BASH_REQUIRED.match?(cmd)
+        return "cmd" if platform == :windows && cmd_builtin?(cmd)
+        return POWERSHELL if PS_FINGERPRINT.match?(cmd)
+        return "bash" if platform == :windows && SUBSTITUTION.match?(cmd)
+
+        default_shell(platform)
+      end
+
+      # First token is a cmd.exe builtin with no standalone binary — cmd.exe
+      # is the only interpreter that can run it (see CMD_BUILTINS rationale).
+      def cmd_builtin?(cmd)
+        CMD_BUILTINS.include?(cmd.to_s.split.first.to_s.downcase)
+      end
+    end
+  end
+end

data/lib/rubik/sandbox.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "sandbox/runner"
+
+module Rubik
+  module Sandbox
+  end
+end