silas 0.1.1

data/lib/silas/configuration.rb

@@ -0,0 +1,164 @@
+module Silas
+  class Configuration
+    # Inference engine seam: :ruby_llm (Phase 1) or :agent_sdk (stub).
+    attr_accessor :engine
+    # Auth mode for :agent_sdk — :api_key or :oauth (subscription).
+    attr_accessor :auth
+    # Default model when agent.yml doesn't specify one.
+    attr_accessor :default_model
+    # Active Job queue for agent turns.
+    attr_accessor :queue_name
+    # Optional hook wrapping every model call — e.g. ruby_llm-resilience:
+    #   config.around_model_call = ->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }
+    attr_accessor :around_model_call
+    # How long a parked approval (or in-doubt invocation) waits before expiring.
+    # eve parks forever; Silas expires (parked-forever ghosts are a bug, not a feature).
+    attr_accessor :approval_ttl
+    # Hard cap on model calls per turn (agent.yml can lower it per-agent).
+    attr_accessor :max_steps
+    # Continuation isolation for loop steps. true in production (persistence
+    # per step — the durability contract); specs may disable for inline runs.
+    attr_accessor :isolate_steps
+    # Injectable seams until/beyond the Registry: name -> tool object, the tool
+    # schema list for the model, and the definitions digest for the
+    # nondeterminism guard. The Registry wires real defaults at boot.
+    attr_accessor :tool_resolver, :tool_definitions, :definitions_digest, :skills, :schedules
+    # Subagents: the roster (name+description) and per-name scope builders, plus
+    # the active-agent overrides swapped in during a nested run.
+    attr_accessor :subagent_index, :subagent_scopes, :agent_override, :instructions_dir
+    # Channels: name -> Channel subclass (wired by the Registry). Slack creds
+    # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
+    attr_accessor :channel_resolver
+    attr_writer :slack_signing_secret, :slack_bot_token
+    # :agent_sdk engine knobs.
+    attr_accessor :agent_sdk_claude_bin, :agent_sdk_model, :agent_sdk_mcp_host,
+                  :agent_sdk_mcp_timeout_ms, :agent_sdk_cli_version_range
+    # Inbox (mountable UI at /silas/inbox).
+    #   inbox_auth        — deny-by-default lambda; the host renders/head-404s to
+    #                       DENY and passes by NOT rendering (resilience pattern).
+    #   inbox_public_read — reads render for anyone; approve/decline still gated.
+    #   inbox_actor       — controller -> identity string (approved_by/decline by:).
+    #   model_prices      — model id -> {in:, out:} cost-units per 1k tokens,
+    #                       where 1_000_000 units = $1 (so a $3/M-token input rate
+    #                       is 3000 units/1k). Cost.format divides by 1e6.
+    attr_accessor :inbox_auth, :inbox_public_read, :inbox_actor, :model_prices
+    # Force-disable live broadcasting even when turbo-rails is present (nil = auto).
+    attr_accessor :inbox_streaming
+    # Evals: where *_eval.rb scenarios live, and an optional custom LLM grader.
+    attr_accessor :eval_dir, :eval_grader
+    # Connections: a test seam for injecting a fake MCP client ->(connection){ client }.
+    attr_accessor :mcp_client_factory
+    # Sandbox: :none (default, code exec off) | :docker | any object responding
+    # to #run. Docker knobs are inert unless :docker.
+    attr_accessor :sandbox, :sandbox_image, :sandbox_network, :sandbox_memory,
+                  :sandbox_cpus, :sandbox_pids, :sandbox_workdir, :sandbox_docker_bin, :sandbox_timeout
+
+    def slack_signing_secret
+      @slack_signing_secret || Rails.application.credentials.dig(:silas, :slack, :signing_secret)
+    end
+
+    def slack_bot_token
+      @slack_bot_token || Rails.application.credentials.dig(:silas, :slack, :bot_token)
+    end
+
+    def initialize
+      @engine = :ruby_llm
+      @auth = :api_key
+      @default_model = "claude-sonnet-5"
+      @queue_name = :default
+      @around_model_call = nil
+      @approval_ttl = 7.days
+      @max_steps = 25
+      @isolate_steps = true
+      @tool_resolver = nil
+      @tool_definitions = nil
+      @definitions_digest = nil
+      @skills = nil
+      @schedules = nil
+      @subagent_index = nil
+      @subagent_scopes = nil
+      @agent_override = nil
+      @instructions_dir = nil
+      @channel_resolver = nil
+      @slack_signing_secret = nil
+      @slack_bot_token = nil
+      @agent_sdk_claude_bin = "claude"
+      @agent_sdk_model = nil # falls back to the agent model; must be a CLI-accepted id
+      @agent_sdk_mcp_host = "127.0.0.1"
+      @agent_sdk_mcp_timeout_ms = 15_000
+      @agent_sdk_cli_version_range = ">= 2.1.150, < 3"
+      @eval_dir = "test/agent_evals"
+      @eval_grader = nil
+      @sandbox = :none
+      @sandbox_image = nil
+      @sandbox_network = "none"
+      @sandbox_memory = "512m"
+      @sandbox_cpus = "1"
+      @sandbox_pids = 256
+      @sandbox_workdir = "/workspace"
+      @sandbox_docker_bin = "docker"
+      @sandbox_timeout = 30
+      @inbox_auth = ->(controller) { controller.head :not_found } # deny by default
+      @inbox_public_read = false
+      @inbox_actor = ->(controller) { controller.try(:current_user)&.try(:email) || "inbox" }
+      # Current Claude rates as cost-units per 1k tokens (1e6 units = $1):
+      # Sonnet $3/$15, Opus $15/$75, Haiku $1/$5 per million tokens.
+      @model_prices = {
+        "claude-sonnet-5" => { in: 3000, out: 15_000 },
+        "claude-opus-4-8" => { in: 15_000, out: 75_000 },
+        "claude-haiku-4-5-20251001" => { in: 1000, out: 5000 }
+      }
+    end
+
+    def validate!
+      boot_guard!
+      self
+    end
+
+    # PLAN.md §1, non-negotiable: raise if subscription OAuth is configured
+    # while an API key is present — the key would silently win and bill credits.
+    # The inverse also holds: :agent_sdk runs --bare (API-key auth only), so
+    # api_key mode needs a key present.
+    def boot_guard!
+      if engine == :agent_sdk && auth == :oauth && ENV["ANTHROPIC_API_KEY"].present?
+        raise BootGuardError,
+              "engine :agent_sdk with auth: :oauth is configured, but ANTHROPIC_API_KEY exists " \
+              "in the environment. The key would silently override subscription OAuth and drain " \
+              "API credits. Unset ANTHROPIC_API_KEY or switch to auth: :api_key."
+      end
+
+      if engine == :agent_sdk && auth == :api_key && ENV["ANTHROPIC_API_KEY"].blank?
+        raise BootGuardError,
+              "engine :agent_sdk uses --bare (API-key auth only) but ANTHROPIC_API_KEY is not set."
+      end
+
+      warn_unsafe_queue_adapter!
+    end
+
+    # Silas's durability and exactly-once guarantees rest on the queue adapter:
+    # a turn's jobs must run one-at-a-time and continuation retries must run in a
+    # FRESH execution after the prior one committed. The in-process Async adapter
+    # (ActiveJob's dev default) breaks both — it runs a re-enqueued continuation
+    # on a thread pool concurrently with the original, which double-executes
+    # steps and violates the single-active-turn invariant (a re-run model call
+    # mints new tool_call ids the ledger cannot dedup). Solid Queue — or any
+    # durable, serializing, DB-backed adapter — is required to run agents; the
+    # synchronous :inline adapter is safe for scripts and demos (no durability).
+    def warn_unsafe_queue_adapter!
+      return unless defined?(::ActiveJob::Base)
+
+      name = ::ActiveJob::Base.queue_adapter.class.name.to_s
+      return unless name.include?("AsyncAdapter")
+
+      message = "[Silas] ActiveJob is using the in-process Async queue adapter. " \
+                "This runs continuation retries on a thread pool concurrently with " \
+                "the original job, which double-executes agent steps and breaks " \
+                "exactly-once tool effects. Use :solid_queue (production) or " \
+                ":inline (scripts/demos). See Silas DEPLOY.md."
+      (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    rescue StandardError
+      # A diagnostic must never break boot.
+      nil
+    end
+  end
+end

data/lib/silas/connection.rb

@@ -0,0 +1,77 @@
+require "yaml"
+
+module Silas
+  # A typed MCP integration declared by app/agent/connections/<name>.yml. Filename
+  # is identity. Holds the credential PATH, never the secret (resolved from Rails
+  # credentials at call time). Data-only (eve's shape).
+  class Connection
+    TRANSPORTS = %w[http].freeze
+    APPROVALS  = %i[never once always].freeze
+    EFFECTS    = %i[at_most_once idempotent].freeze # not transactional: a remote call can't share our DB txn
+
+    attr_reader :name, :transport, :url, :approval, :effect
+
+    def self.parse(path)
+      attrs = YAML.safe_load(File.read(path)) || {}
+      attrs.empty? ? nil : new(File.basename(path, ".yml"), attrs)
+    end
+
+    def initialize(name, attrs)
+      @name = name
+      @transport = attrs.fetch("transport", "http")
+      @url = attrs["url"]
+      @auth = attrs["auth"] || {}
+      @approval = (attrs["approval"] || "never").to_sym
+      @effect = (attrs["effect"] || "at_most_once").to_sym
+      validate!
+    end
+
+    def client = Mcp::Client.new(url: url, headers: auth_headers)
+
+    def auth_headers
+      case @auth["type"]
+      when "bearer" then { "Authorization" => "Bearer #{secret!}" }
+      when "header" then { @auth.fetch("header") => secret! }
+      else {}
+      end
+    end
+
+    private
+
+    def secret!
+      path = @auth.fetch("credential")
+      val = Rails.application.credentials.dig(*path.split(".").map(&:to_sym))
+      raise Error, "connection #{name}: missing credential #{path.inspect}" if val.blank?
+
+      val
+    end
+
+    def validate!
+      raise Error, "connection #{name}: url required" if url.blank?
+      raise Error, "connection #{name}: transport #{transport.inspect} unsupported (v1: http)" unless TRANSPORTS.include?(transport)
+      raise Error, "connection #{name}: approval #{approval.inspect} invalid" unless APPROVALS.include?(approval)
+      raise Error, "connection #{name}: effect #{effect.inspect} invalid" unless EFFECTS.include?(effect)
+    end
+
+    # One remote tool, resolved. Quacks like a resolved Silas::Tool for the
+    # Ledger (approval_policy / effect_mode / session= / call) without being a
+    # Silas::Tool subclass — its schema is the remote inputSchema.
+    class RemoteTool
+      attr_accessor :session
+
+      def initialize(connection:, remote_name:, client: nil)
+        @connection = connection
+        @remote_name = remote_name
+        @client = client || connection.client
+      end
+
+      def approval_policy = @connection.approval
+      def effect_mode     = @connection.effect
+
+      def call(**args)
+        @client.call_tool(@remote_name, args.deep_stringify_keys) ||
+          { "isError" => true, "content" => [ { "type" => "text", "text" => "no result" } ] }
+      end
+    end
+  end
+end

data/lib/silas/connections.rb

@@ -0,0 +1,52 @@
+module Silas
+  # Discovery + boot-warm for app/agent/connections/*.yml. Lists each remote MCP
+  # server's tools ONCE at boot (cached), surfaces them namespaced as
+  # "<connection>__<tool>" (model-visible -> in the digest), and resolves those
+  # names to fresh RemoteTool instances for the Ledger.
+  class Connections
+    def initialize(root:, client_factory: nil)
+      @root = Pathname(root)
+      @client_factory = client_factory
+      @definitions = []
+      @by_name = {}
+    end
+
+    def descriptors
+      @descriptors ||= Dir[@root.join("app/agent/connections/*.yml")].sort.filter_map { |f| Connection.parse(f) }
+    end
+
+    # Boot-time tools/list, cached. Fail-loud (like the Registry's boot tool
+    # validation): a misconfigured/unreachable connection raises HERE, never
+    # inside a turn or a mid-turn digest check.
+    def warm!
+      return self if @warmed
+
+      descriptors.each do |conn|
+        client = @client_factory&.call(conn) || conn.client
+        client.list_tools.each do |remote|
+          ns = "#{conn.name}__#{remote['name']}"
+          @definitions << {
+            "name" => ns, "description" => remote["description"].to_s,
+            "input_schema" => remote["inputSchema"] || { "type" => "object", "properties" => {} }
+          }
+          @by_name[ns] = [ conn, remote["name"] ]
+        end
+      rescue StandardError => e
+        raise Error, "connection #{conn.name}: tools/list failed at boot — #{e.class}: #{e.message}"
+      end
+      @warmed = true
+      self
+    end
+
+    def definitions = @definitions.dup
+
+    def resolve(name)
+      pair = @by_name[name]
+      return nil unless pair
+
+      conn, remote = pair
+      client = @client_factory&.call(conn) || conn.client
+      Connection::RemoteTool.new(connection: conn, remote_name: remote, client: client)
+    end
+  end
+end

data/lib/silas/engine.rb

@@ -0,0 +1,36 @@
+module Silas
+  # The Rails engine (not to be confused with inference adapters under
+  # Silas::Engines::*). Full engine: Silas is Rails-native by thesis.
+  class Engine < ::Rails::Engine
+    isolate_namespace Silas
+
+    # Make app/agent/ a first-class app directory: files there autoload under
+    # the bare Agent namespace, so app/agent/tools/issue_refund.rb defines
+    # Agent::Tools::IssueRefund. Tool identity remains the filename.
+    initializer "silas.agent_directory" do |app|
+      agent_dir = app.root.join("app/agent")
+      next unless agent_dir.exist?
+
+      unless defined?(::Agent)
+        Object.const_set(:Agent, Module.new)
+      end
+      app.autoloaders.main.push_dir(agent_dir, namespace: ::Agent)
+
+      # Markdown/YAML (instructions.md, agent.yml, skills/*.md) are not Ruby;
+      # keep Zeitwerk away from them. tools/, schedules/ (.rb handlers), and
+      # channels/ all autoload under the Agent namespace via push_dir above.
+      app.autoloaders.main.ignore(agent_dir.join("skills"))
+    end
+
+    initializer "silas.boot_guard", after: :load_config_initializers do
+      Silas.config.boot_guard!
+    end
+
+    # Registry rebuilds on every code reload in development, once in production.
+    initializer "silas.registry" do |app|
+      next unless app.root.join("app/agent").exist?
+
+      app.config.to_prepare { Silas::Registry.install!(root: Rails.root) }
+    end
+  end
+end

data/lib/silas/engines/agent_sdk.rb

@@ -0,0 +1,75 @@
+module Silas
+  module Engines
+    # The engine-owned adapter: one `claude -p` subprocess runs a whole agentic
+    # turn, calling back into Silas tools over an in-worker HTTP MCP endpoint
+    # whose tools/call goes THROUGH the Ledger (exactly-once within the run).
+    # The mirror image of :ruby_llm — Claude Code owns the loop; Silas hosts the
+    # tools and maps the NDJSON stream onto durable rows.
+    #
+    # v1 contract (honestly weaker than :ruby_llm): exactly-once WITHIN a run,
+    # approval :never tools only, and fail-closed on mid-subprocess worker kill.
+    class AgentSdk < Base
+      def self.loop_ownership = :engine
+
+      def execute_step(context, &on_event)
+        turn = context[:turn]
+        Silas::AgentSdk::VersionGuard.assert!(Silas.config.agent_sdk_claude_bin)
+        assert_api_key!
+
+        tools = allowed_tools(context[:tools])
+        server = Mcp::Server.start(turn: turn, step: context[:step], tools: tools, resolver: Silas.tool_resolver)
+        cli = nil
+        begin
+          server.await_ready!
+          cli = build_cli(context, server, tools)
+          parser = Silas::AgentSdk::StreamParser.new
+          cli.stream do |line|
+            parser.ingest(line) do |event|
+              persist_session_id!(turn, parser)
+              on_event&.call(event)
+              ActiveSupport::Notifications.instrument("silas.agent_sdk.event", turn_id: turn.id, type: event.type)
+            end
+          end
+          parser.to_result
+        ensure
+          cli&.terminate
+          server.stop
+        end
+      end
+
+      private
+
+      def build_cli(context, server, tools)
+        Silas::AgentSdk::Cli.new(
+          bin: Silas.config.agent_sdk_claude_bin,
+          prompt: context[:turn].input,
+          system: context[:system],
+          model: Silas.config.agent_sdk_model || context[:model],
+          mcp_url: server.mcp_url,
+          allowed: tools.map { |d| "mcp__silas__#{d['name']}" }
+        )
+      end
+
+      # v1 excludes approval-gated tools entirely (both tools/list and
+      # --allowedTools) — an engine-owned subprocess can't park cheaply.
+      def allowed_tools(definitions)
+        kept = definitions.select { |d| Silas.tool_resolver.call(d["name"]).approval_policy == :never }
+        dropped = definitions.map { |d| d["name"] } - kept.map { |d| d["name"] }
+        Rails.logger&.info("silas: :agent_sdk excludes approval-gated tools #{dropped.inspect}") if dropped.any?
+        kept
+      end
+
+      def persist_session_id!(turn, parser)
+        return unless turn.cli_session_id.nil? && parser.session_id.present?
+
+        turn.update_columns(cli_session_id: parser.session_id)
+      end
+
+      def assert_api_key!
+        return if ENV["ANTHROPIC_API_KEY"].present?
+
+        raise Silas::BootGuardError, ":agent_sdk uses --bare (API-key auth only); set ANTHROPIC_API_KEY"
+      end
+    end
+  end
+end

data/lib/silas/engines/base.rb

@@ -0,0 +1,30 @@
+module Silas
+  # Streamed event from an engine (or the framework) during a step.
+  # Types: :text_delta, :tool_call, :thinking, :usage — and :approval_request,
+  # which only :engine-owned loops (agent_sdk) emit; in :framework-owned loops
+  # approvals are a Ledger concern, never an engine event.
+  Event = Data.define(:type, :payload)
+
+  module Engines
+    # The inference seam. An engine executes exactly ONE model call for a step
+    # and reports what came back; the framework owns the loop, the ledger owns
+    # tool execution.
+    class Base
+      # :framework — Silas's AgentLoopJob drives the loop (ruby_llm).
+      # :engine    — the engine drives its own loop (agent_sdk, future).
+      def self.loop_ownership = :framework
+
+      # context: { turn:, index:, system:, messages:, tools:, model:, limits: }
+      # Yields Silas::Event objects as they stream; returns a Result.
+      def execute_step(context, &on_event)
+        raise NotImplementedError, "#{self.class} must implement #execute_step"
+      end
+    end
+
+    Result = Data.define(:blocks, :tool_calls, :stop_reason, :usage) do
+      def terminal? = tool_calls.empty?
+    end
+
+    ToolCall = Data.define(:id, :name, :arguments)
+  end
+end

data/lib/silas/engines/ruby_llm.rb

@@ -0,0 +1,136 @@
+module Silas
+  module Engines
+    # The :ruby_llm adapter: ONE model call per step, streamed, with tool
+    # interception. Silas's Ledger owns tool execution, so tools are registered
+    # as halt-proxies — RubyLLM sees the schemas, but the moment the model
+    # requests a tool the proxy halts the chat loop and the calls are handed
+    # back to the framework untouched.
+    class RubyLLM < Base
+      INTERCEPTED = "__silas_intercepted__".freeze
+
+      def self.loop_ownership = :framework
+
+      def execute_step(context, &on_event)
+        chat = build_chat(context, &on_event)
+
+        response = ActiveSupport::Notifications.instrument("silas.step",
+                                                           turn_id: context[:turn]&.id,
+                                                           index: context[:index],
+                                                           model: context[:model]) do
+          chat.complete
+        end
+
+        to_result(chat, response)
+      end
+
+      private
+
+      def build_chat(context, &on_event)
+        chat = ::RubyLLM.chat(model: context[:model])
+        chat.with_instructions(context[:system]) if context[:system].present?
+        context[:tools].each { |definition| chat.with_tool(HaltProxy.new(definition)) }
+
+        replay_history(chat, context[:messages])
+
+        if on_event
+          chat.on_new_message { on_event.call(Event.new(type: :message_start, payload: {})) }
+        end
+        chat
+      end
+
+      # Rebuild the provider conversation from Silas's canonical rows. The last
+      # user message is delivered via ask-equivalent add_message; RubyLLM sends
+      # the whole array on complete.
+      def replay_history(chat, messages)
+        i = 0
+        while i < messages.length
+          msg = messages[i]
+          case msg[:role]
+          when "user"
+            chat.add_message(role: :user, content: msg[:content])
+            i += 1
+          when "assistant"
+            chat.add_message(
+              role: :assistant,
+              content: text_from(msg[:content]),
+              tool_calls: tool_calls_from(msg[:content])
+            )
+            i += 1
+          when "tool"
+            # Anthropic requires every tool_result for one assistant turn to sit
+            # in a single user message. The model can emit parallel tool_use
+            # blocks, so batch all consecutive tool results into one Raw message
+            # (a one-element batch is the ordinary single-tool-call case).
+            first_id = msg[:tool_call_id]
+            blocks = []
+            while i < messages.length && messages[i][:role] == "tool"
+              t = messages[i]
+              blocks << {
+                type: "tool_result",
+                tool_use_id: t[:tool_call_id],
+                content: JSON.generate(t[:content])
+              }
+              i += 1
+            end
+            chat.add_message(role: :tool, tool_call_id: first_id,
+                             content: ::RubyLLM::Content::Raw.new(blocks))
+          else
+            i += 1
+          end
+        end
+      end
+
+      def text_from(blocks)
+        Array(blocks).select { |b| b["type"] == "text" }.map { |b| b["text"] }.join
+      end
+
+      def tool_calls_from(blocks)
+        calls = Array(blocks).select { |b| b["type"] == "tool_call" }
+        return nil if calls.empty?
+
+        calls.to_h do |b|
+          [ b["id"], ::RubyLLM::ToolCall.new(id: b["id"], name: b["name"], arguments: b["arguments"]) ]
+        end
+      end
+
+      # The halt-proxies stop the loop after the assistant's tool_use message
+      # was recorded on the chat; pull the LAST assistant message for the step.
+      def to_result(chat, response)
+        assistant = chat.messages.reverse.find { |m| m.role.to_s == "assistant" } || response
+
+        blocks = []
+        text = assistant.content.to_s
+        blocks << { "type" => "text", "text" => text } if text.present?
+
+        tool_calls = (assistant.tool_calls || {}).values.map do |tc|
+          blocks << { "type" => "tool_call", "id" => tc.id, "name" => tc.name,
+                      "arguments" => tc.arguments || {} }
+          ToolCall.new(id: tc.id, name: tc.name, arguments: (tc.arguments || {}).stringify_keys)
+        end
+
+        Result.new(
+          blocks: blocks,
+          tool_calls: tool_calls,
+          stop_reason: tool_calls.any? ? "tool_use" : "end_turn",
+          usage: { input_tokens: assistant.tokens&.input, output_tokens: assistant.tokens&.output }
+        )
+      end
+
+      # Presents an Silas tool schema to RubyLLM; halts instead of executing.
+      class HaltProxy < ::RubyLLM::Tool
+        def initialize(definition)
+          super()
+          @definition = definition
+        end
+
+        def name = @definition["name"]
+        def description = @definition["description"]
+        def params_schema = @definition["input_schema"]
+
+        def execute(**)
+          ::RubyLLM::Tool::Halt.new(INTERCEPTED)
+        end
+      end
+    end
+  end
+end

data/lib/silas/errors.rb

@@ -0,0 +1,26 @@
+module Silas
+  class Error < StandardError; end
+
+  # The :agent_sdk + OAuth footgun (PLAN.md boot guard, non-negotiable): an
+  # ANTHROPIC_API_KEY in the environment would silently override subscription
+  # OAuth and drain credits.
+  class BootGuardError < Error; end
+
+  # A continuation checkpoint occurred inside a ledger transaction. Checkpoints
+  # raise Interrupt, which would roll back the ledger row + side effects while
+  # the continuation believes progress was made (spike finding #5).
+  class CheckpointInLedgerError < Error; end
+
+  # The live tool/skill definitions diverged from the turn's snapshot digest —
+  # e.g. a deploy changed the agent mid-turn. Fail loudly, never resume into a
+  # different agent.
+  class NondeterminismError < Error; end
+
+  # A second turn was started while one is active for the session. The partial
+  # unique index is the backstop; this is the friendly front door.
+  class TurnInProgressError < Error; end
+
+  # Sandbox misconfiguration or exec failure (fail-loud, like BootGuardError).
+  class SandboxError < Error; end
+  class SandboxDisabledError < SandboxError; end
+end