agentboard 0.2.0

data/lib/agentboard/subprocess.rb

@@ -0,0 +1,168 @@
+module Agentboard
+  # Safe subprocess spawning shared by verification and provider launches.
+  #
+  # - argv arrays only (no shell, no interpolation of ticket text)
+  # - own process group so cancellation reaches every child
+  # - scrubbed environment (allowlist) to avoid leaking credentials
+  # - continuous draining with a byte cap; truncation is marked, never silent
+  module Subprocess
+    ENV_ALLOWLIST = %w[PATH HOME USER LOGNAME SHELL LANG LC_ALL LC_CTYPE TERM TMPDIR TZ
+                       RBENV_VERSION RBENV_ROOT MISE_DATA_DIR MISE_CONFIG_DIR ASDF_DIR ASDF_DATA_DIR
+                       GEM_HOME GEM_PATH BUNDLE_PATH BUNDLE_GEMFILE RUBYOPT RUBYLIB
+                       NODE_PATH XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME SSL_CERT_FILE].freeze
+
+    Result = Struct.new(:exit_code, :signal, :timed_out, :cancelled, :duration, :output, :truncated, keyword_init: true) do
+      def success? = exit_code == 0 && !timed_out && !cancelled
+    end
+
+    module_function
+
+    def scrubbed_env(extra = {}, passthrough: [])
+      base = ENV.to_h.slice(*(ENV_ALLOWLIST + Array(passthrough)))
+      base.merge(extra.transform_keys(&:to_s).transform_values(&:to_s))
+    end
+
+    # Spawns argv; yields each output chunk (already redacted) if a block is given.
+    # Returns a handle hash { pid:, pgid:, reader: }.
+    def spawn(argv, chdir:, env: {}, passthrough_env: [], stdin_data: nil)
+      raise ArgumentError, "argv must be a non-empty Array" unless argv.is_a?(Array) && argv.any?
+      raise ArgumentError, "argv elements must be strings" unless argv.all? { |a| a.is_a?(String) }
+
+      reader, writer = IO.pipe
+      in_r, in_w = IO.pipe
+      pid = ::Process.spawn(scrubbed_env(env, passthrough: passthrough_env), *argv,
+                            chdir: chdir.to_s, pgroup: true, in: in_r, out: writer, err: writer,
+                            unsetenv_others: true, close_others: true)
+      writer.close
+      in_r.close
+      if stdin_data
+        Thread.new do
+          in_w.write(stdin_data)
+        rescue IOError, Errno::EPIPE
+          nil
+        ensure
+          in_w.close unless in_w.closed?
+        end
+      else
+        in_w.close
+      end
+      { pid: pid, pgid: pid, reader: reader }
+    end
+
+    # Runs to completion with timeout/cancellation. `cancel_check` is polled.
+    def run(argv, chdir:, timeout:, env: {}, max_bytes: 1_000_000, grace: 5, cancel_check: nil, log_io: nil, passthrough_env: [], stdin_data: nil, &on_chunk)
+      started = monotonic
+      handle = spawn(argv, chdir: chdir, env: env, passthrough_env: passthrough_env, stdin_data: stdin_data)
+      buffer = +""
+      truncated = false
+      timed_out = false
+      cancelled = false
+      reader = handle[:reader]
+
+      loop do
+        if timeout && monotonic - started > timeout
+          timed_out = true
+          terminate(handle[:pgid], grace: grace)
+          break
+        end
+        if cancel_check&.call
+          cancelled = true
+          terminate(handle[:pgid], grace: grace)
+          break
+        end
+        ready = IO.select([ reader ], nil, nil, 0.2)
+        next unless ready
+
+        begin
+          chunk = reader.read_nonblock(16_384)
+        rescue IO::WaitReadable
+          next
+        rescue EOFError
+          break
+        end
+        chunk = Redactor.redact(chunk.force_encoding("UTF-8").scrub)
+        log_io&.write(chunk)
+        on_chunk&.call(chunk)
+        if buffer.bytesize < max_bytes
+          buffer << chunk.byteslice(0, max_bytes - buffer.bytesize)
+        else
+          truncated = true
+        end
+      end
+      reader.close unless reader.closed?
+      _, status = ::Process.wait2(handle[:pid])
+      Result.new(exit_code: status.exitstatus, signal: status.termsig, timed_out: timed_out, cancelled: cancelled,
+                 duration: monotonic - started, output: truncated ? buffer + "\n[agentboard: output truncated at #{max_bytes} bytes]\n" : buffer,
+                 truncated: truncated)
+    rescue Errno::ENOENT => e
+      Result.new(exit_code: 127, signal: nil, timed_out: false, cancelled: false, duration: 0, output: "command not found: #{argv.first} (#{e.class})", truncated: false)
+    end
+
+    # Graceful SIGTERM to the process group, SIGKILL after grace period.
+    def terminate(pgid, grace: 5)
+      signal_group("TERM", pgid)
+      deadline = monotonic + grace
+      while monotonic < deadline
+        return true unless group_alive?(pgid)
+
+        sleep 0.05
+      end
+      signal_group("KILL", pgid)
+      true
+    end
+
+    def signal_group(sig, pgid)
+      ::Process.kill(sig, -pgid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def group_alive?(pgid)
+      ::Process.kill(0, -pgid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    def alive?(pid)
+      ::Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    # Best-effort process identity: start time + command, used to avoid trusting reused PIDs.
+    def fingerprint(pid)
+      out, _e, st = Open3.capture3("ps", "-o", "lstart=,command=", "-p", pid.to_s)
+      st.success? ? Digest::SHA256.hexdigest(out.strip)[0, 32] : nil
+    rescue StandardError
+      nil
+    end
+
+    # Resource usage of a whole process group: { rss_kb:, cpu_seconds:, processes: }.
+    # `ps -A -o pid,pgid,rss,time` works on both macOS (BSD ps) and Linux (procps).
+    def group_usage(pgid)
+      out, _e, st = Open3.capture3("ps", "-A", "-o", "pgid=,rss=,time=")
+      return nil unless st.success?
+
+      rows = out.lines.map(&:split).select { |r| r[0].to_i == pgid.to_i }
+      { rss_kb: rows.sum { |r| r[1].to_i }, cpu_seconds: rows.sum { |r| parse_cpu_time(r[2]) }.round(2), processes: rows.size }
+    rescue StandardError
+      nil
+    end
+
+    # Accepts [[dd-]hh:]mm:ss[.xx]
+    def parse_cpu_time(str)
+      days, rest = str.to_s.include?("-") ? str.split("-", 2) : [ 0, str.to_s ]
+      parts = rest.split(":").map(&:to_f)
+      parts.unshift(0) while parts.size < 3
+      days.to_i * 86_400 + parts[0] * 3600 + parts[1] * 60 + parts[2]
+    end
+
+    def monotonic = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/agentboard/templates/Dockerfile.agent

@@ -0,0 +1,21 @@
+# AgentBoard agent sandbox image. Build with: bundle exec agentboard sandbox build
+# Contains the project's Ruby toolchain and gems plus the agent CLIs. It runs as your UID
+# with a read-only root filesystem; network egress goes only through the allowlisting proxy.
+ARG RUBY_VERSION=__RUBY_VERSION__
+FROM ruby:${RUBY_VERSION}-slim
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates curl build-essential libyaml-dev libpq-dev pkg-config nodejs npm \
+ && rm -rf /var/lib/apt/lists/*
+
+# Agent CLIs (pin versions to the ones validated in AgentBoard's compatibility manifest).
+RUN npm install -g @anthropic-ai/claude-code @openai/codex && npm cache clean --force
+
+# Project gems, so agents can run the test suite inside the sandbox. The development group
+# is skipped: it usually holds tooling (and local path gems) the test suite does not need.
+ENV BUNDLE_PATH=/usr/local/bundle BUNDLE_WITHOUT=development
+COPY Gemfile Gemfile.lock* /tmp/app/
+RUN cd /tmp/app && bundle install --jobs 4 && rm -rf /tmp/app && chmod -R a+rX /usr/local/bundle
+
+RUN git config --system --add safe.directory '*'
+WORKDIR /workspace

data/lib/agentboard/verification.rb

@@ -0,0 +1,79 @@
+require "agentboard/subprocess"
+
+module Agentboard
+  module Verification
+    # Administrator-defined allowlist of verification commands (spec §29.1).
+    # Workflows and agents can reference commands only by name.
+    class Catalog
+      Command = Struct.new(:name, :argv, :timeout_seconds, :required, :working_directory, :env, keyword_init: true) do
+        def digest = Ids.canonical_digest(name: name, argv: argv, cwd: working_directory, env: env)
+      end
+
+      attr_reader :commands
+
+      def initialize(hash)
+        @commands = hash.to_h.to_h do |name, spec|
+          spec = spec.to_h.transform_keys(&:to_s)
+          argv = spec["argv"]
+          unless argv.is_a?(Array) && argv.any? && argv.all? { |a| a.is_a?(String) && !a.empty? }
+            raise Error.validation_failed("verification command #{name} needs a non-empty argv array of strings")
+          end
+
+          [ name.to_s, Command.new(name: name.to_s, argv: argv.freeze, timeout_seconds: (spec["timeout_seconds"] || 600).to_i.clamp(1, 86_400),
+                                   required: spec.fetch("required", true) != false, working_directory: spec["working_directory"] || "worktree",
+                                   env: (spec["env"] || {}).to_h.transform_keys(&:to_s)) ]
+        end
+      end
+
+      def fetch(name)
+        commands.fetch(name.to_s) { raise Error.policy_denied("Command #{name} is not in the approved catalog") }
+      end
+
+      def names = commands.keys
+      def required_names = commands.values.select(&:required).map(&:name)
+      def each(&) = commands.values.each(&)
+    end
+
+    # Executes catalog commands directly (no shell) inside a directory and binds the result
+    # to the exact head SHA. A dirty tree is never bound to a commit.
+    class Runner
+      Outcome = Struct.new(:name, :status, :exit_code, :commit_sha, :command_digest, :output, :duration, :required, keyword_init: true)
+
+      def initialize(catalog:, max_bytes: 512 * 1024)
+        @catalog = catalog
+        @max_bytes = max_bytes
+      end
+
+      def run(name, chdir:, cancel_check: nil, timeout: nil, &on_chunk)
+        cmd = @catalog.fetch(name)
+        repo = Git::Repository.new(chdir)
+        head = repo.head_sha(chdir: chdir)
+        dirty = !repo.clean?(chdir: chdir)
+        limit = [ cmd.timeout_seconds, timeout ].compact.min
+        env = cmd.env.merge("CI" => "1", "AGENTBOARD_VERIFICATION" => "1")
+        argv = cmd.argv
+        container = nil
+        if ContainerSandbox.enabled?
+          raise Error.capability_unavailable("Container sandbox requested but #{ContainerSandbox.settings["runtime"]} is not running") unless ContainerSandbox.available?
+
+          container = ContainerSandbox.container_name
+          argv = ContainerSandbox.wrap(cmd.argv, workdir: chdir, env: env, name: container)
+        end
+        result = Subprocess.run(argv, chdir: chdir, timeout: limit, env: env, max_bytes: @max_bytes, cancel_check: cancel_check, &on_chunk)
+        ContainerSandbox.kill(container) if container && (result.timed_out || result.cancelled)
+        # If the tree changed during the run, the result cannot be attributed to `head`.
+        head_after = repo.head_sha(chdir: chdir)
+        bound_sha = (dirty || head_after != head) ? "unbound:#{head}" : head
+        status =
+          if result.timed_out then "timeout"
+          elsif result.cancelled then "error"
+          elsif result.exit_code == 127 && result.output.start_with?("command not found") then "error"
+          elsif result.success? then "passed"
+          else "failed"
+          end
+        Outcome.new(name: cmd.name, status: status, exit_code: result.exit_code, commit_sha: bound_sha, command_digest: cmd.digest,
+                    output: result.output, duration: result.duration, required: cmd.required)
+      end
+    end
+  end
+end

data/lib/agentboard/version.rb

@@ -0,0 +1,3 @@
+module Agentboard
+  VERSION = "0.2.0"
+end

data/lib/agentboard/workflows/condition.rb

@@ -0,0 +1,166 @@
+module Agentboard
+  module Workflows
+    # Restricted condition grammar (spec §28.2) — never `eval`.
+    #
+    #   expr    := or
+    #   or      := and ("or" and)*
+    #   and     := unary ("and" unary)*
+    #   unary   := "not" unary | primary
+    #   primary := "(" expr ")" | ref op literal | "true" | "false"
+    #   ref     := steps.<id>.(status|output.<key>) | ticket.(priority|kind|status)
+    #   op      := == | != | < | <= | > | >=
+    #   literal := 'string' | "string" | integer | true | false
+    class Condition
+      class SyntaxError < StandardError; end
+
+      TOKEN = /\s*(?:(\(|\))|(==|!=|<=|>=|<|>)|('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|(-?\d+)|([A-Za-z_][\w.]*))/
+      REF = /\A(?:steps\.[a-z][a-z0-9_]*\.(?:status|output\.[a-z][a-z0-9_]*)|ticket\.(?:priority|kind|status))\z/
+
+      attr_reader :source
+
+      def self.parse(source) = new(source).tap(&:ast)
+
+      def initialize(source)
+        @source = source.to_s
+        raise SyntaxError, "condition too long" if @source.length > 500
+      end
+
+      def ast = (@ast ||= build)
+
+      def step_refs
+        refs = []
+        walk = ->(node) do
+          case node
+          in [ :cmp, ref, _, _ ] then refs << ref.split(".")[1] if ref.start_with?("steps.")
+          in [ :and | :or, l, r ] then walk.(l); walk.(r)
+          in [ :not, x ] then walk.(x)
+          else nil
+          end
+        end
+        walk.(ast)
+        refs.uniq
+      end
+
+      # context: { "steps" => { "test" => { "status" => "succeeded", "output" => {...} } }, "ticket" => {...} }
+      def evaluate(context) = eval_node(ast, context)
+
+      private
+
+      def build
+        @tokens = tokenize(@source)
+        @pos = 0
+        node = parse_or
+        raise SyntaxError, "unexpected token #{@tokens[@pos].inspect}" if @pos < @tokens.size
+
+        node
+      end
+
+      def tokenize(src)
+        tokens = []
+        rest = src.strip
+        until rest.empty?
+          m = TOKEN.match(rest)
+          raise SyntaxError, "invalid condition near #{rest[0, 20].inspect}" unless m && m.begin(0).zero?
+
+          tokens << if m[1] then [ :paren, m[1] ]
+          elsif m[2] then [ :op, m[2] ]
+          elsif m[3] then [ :lit, m[3][1..-2].gsub(/\\(.)/, '\1') ]
+          elsif m[4] then [ :lit, m[4].to_i ]
+          else
+            word = m[5]
+            case word
+            when "and", "or", "not" then [ :kw, word ]
+            when "true" then [ :lit, true ]
+            when "false" then [ :lit, false ]
+            else
+              raise SyntaxError, "unknown reference #{word}" unless word.match?(REF)
+
+              [ :ref, word ]
+            end
+          end
+          rest = m.post_match.lstrip
+        end
+        tokens
+      end
+
+      def peek = @tokens[@pos]
+      def take = @tokens[@pos].tap { @pos += 1 }
+
+      def parse_or
+        left = parse_and
+        while peek == [ :kw, "or" ]
+          take
+          left = [ :or, left, parse_and ]
+        end
+        left
+      end
+
+      def parse_and
+        left = parse_unary
+        while peek == [ :kw, "and" ]
+          take
+          left = [ :and, left, parse_unary ]
+        end
+        left
+      end
+
+      def parse_unary
+        if peek == [ :kw, "not" ]
+          take
+          return [ :not, parse_unary ]
+        end
+        parse_primary
+      end
+
+      def parse_primary
+        tok = take or raise SyntaxError, "unexpected end of condition"
+        case tok
+        in [ :paren, "(" ]
+          node = parse_or
+          raise SyntaxError, "missing )" unless take == [ :paren, ")" ]
+
+          node
+        in [ :lit, true | false => v ] then [ :lit, v ]
+        in [ :ref, ref ]
+          op = take
+          raise SyntaxError, "expected comparison operator after #{ref}" unless op&.first == :op
+
+          lit = take
+          raise SyntaxError, "expected literal after #{op.last}" unless lit&.first == :lit
+
+          [ :cmp, ref, op.last, lit.last ]
+        else
+          raise SyntaxError, "unexpected token #{tok.last.inspect}"
+        end
+      end
+
+      def eval_node(node, ctx)
+        case node
+        in [ :lit, v ] then v
+        in [ :not, x ] then !eval_node(x, ctx)
+        in [ :and, l, r ] then eval_node(l, ctx) && eval_node(r, ctx)
+        in [ :or, l, r ] then eval_node(l, ctx) || eval_node(r, ctx)
+        in [ :cmp, ref, op, lit ]
+          value = resolve(ref, ctx)
+          compare(value, op, lit)
+        end
+      end
+
+      def resolve(ref, ctx)
+        parts = ref.split(".")
+        parts.reduce(ctx) { |acc, key| acc.is_a?(Hash) ? (acc[key] || acc[key.to_sym]) : nil }
+      end
+
+      def compare(value, op, lit)
+        case op
+        when "==" then value == lit || value.to_s == lit.to_s
+        when "!=" then !(value == lit || value.to_s == lit.to_s)
+        else
+          return false unless value.is_a?(Numeric) && lit.is_a?(Numeric)
+
+          value.public_send(op, lit)
+        end
+      end
+    end
+  end
+end

data/lib/agentboard/workflows/definition.rb

@@ -0,0 +1,208 @@
+module Agentboard
+  module Workflows
+    # Versioned, validated DAG workflow definitions (spec §9, §28.1).
+    class Definition
+      SCHEMA_VERSION = 1
+      STEP_TYPES = %w[agent command verification human_approval git_commit git_pull_request external condition].freeze
+      AGENT_ACTIONS = %w[plan implement review fix_tests summarize].freeze
+      RETRYABLE = %w[provider_unavailable transient_io execution_timeout].freeze
+      MAX_STEPS = 50
+      MAX_ATTEMPTS = 5
+      MAX_TIMEOUT = 24 * 3600
+
+      Step = Struct.new(:id, :type, :provider, :action, :command, :depends_on, :condition, :retry, :timeout_seconds,
+                        :required_role, :config, :integration, keyword_init: true) do
+        def to_h = super.compact.transform_keys(&:to_s)
+        def max_attempts = (retry_policy["max_attempts"] || 1).to_i
+        def retry_policy = (self.retry || {})
+        def retry_on = Array(retry_policy["retry_on"])
+
+        def backoff_for(attempt)
+          list = Array(retry_policy["backoff_seconds"])
+          (list[attempt - 1] || list.last || 0).to_i
+        end
+      end
+
+      attr_reader :name, :version, :steps, :timeout_seconds, :raw
+
+      ADVANCED_STEP_TYPES = %w[external git_pull_request].freeze
+
+      def self.parse_yaml(text, catalog: Agentboard.config.verification_catalog, providers: Providers.registry.keys, enforce_features: false)
+        data = YAML.safe_load(text.to_s, permitted_classes: [], aliases: false)
+        definition = from_h(data, catalog: catalog, providers: providers)
+        if enforce_features && definition.advanced_features.any? && !Agentboard.feature?(:advanced_workflows)
+          raise Error.policy_denied("This workflow uses #{definition.advanced_features.join(", ")}, which require AgentBoard Pro " \
+                                    "(advanced workflows). Sequential agent/command/approval steps are free.",
+                                    errors: [ "requires AgentBoard Pro: #{definition.advanced_features.join(", ")}" ])
+        end
+        definition
+      rescue Psych::Exception => e
+        raise Error.validation_failed("Invalid workflow YAML: #{e.message[0, 200]}")
+      end
+
+      def self.from_h(data, catalog: Agentboard.config.verification_catalog, providers: Providers.registry.keys)
+        new(data, catalog: catalog, providers: providers)
+      end
+
+      def initialize(data, catalog:, providers:)
+        @catalog = catalog
+        @providers = providers.map(&:to_s)
+        @errors = []
+        @raw = data
+        validate_top!(data)
+        raise Error.validation_failed("Invalid workflow: #{@errors.join("; ")}", errors: @errors) if @errors.any?
+      end
+
+      def to_h
+        { "version" => version, "name" => name, "timeout_seconds" => timeout_seconds, "steps" => steps.map(&:to_h) }.compact
+      end
+
+      def digest = Ids.canonical_digest(to_h)
+
+      # Constructs that need AgentBoard Pro (advanced workflows).
+      def advanced_features
+        used = []
+        used << "conditions" if steps.any?(&:condition)
+        used << "retries" if steps.any? { |s| s.max_attempts > 1 }
+        used << "per-step timeouts" if steps.any?(&:timeout_seconds)
+        (steps.map(&:type) & ADVANCED_STEP_TYPES).each { |t| used << "#{t} steps" }
+        used
+      end
+      def step(id) = steps.find { |s| s.id == id }
+      def roots = steps.select { |s| s.depends_on.empty? }
+
+      def topological_order
+        indeg = steps.to_h { |s| [ s.id, s.depends_on.size ] }
+        queue = steps.select { |s| s.depends_on.empty? }.map(&:id)
+        order = []
+        until queue.empty?
+          id = queue.shift
+          order << id
+          steps.each do |s|
+            next unless s.depends_on.include?(id)
+
+            indeg[s.id] -= 1
+            queue << s.id if indeg[s.id].zero?
+          end
+        end
+        order
+      end
+
+      private
+
+      def validate_top!(data)
+        unless data.is_a?(Hash)
+          @errors << "definition must be a mapping"
+          return
+        end
+        data = data.transform_keys(&:to_s)
+        unknown = data.keys - %w[version name steps timeout_seconds description]
+        @errors << "unknown top-level keys: #{unknown.join(", ")}" if unknown.any?
+        @version = data["version"]
+        @errors << "version must be #{SCHEMA_VERSION}" unless @version == SCHEMA_VERSION
+        @name = data["name"].to_s
+        @errors << "name must match /\\A[a-z][a-z0-9_]{0,63}\\z/" unless @name.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+        @timeout_seconds = data["timeout_seconds"]&.to_i
+        @errors << "timeout_seconds out of range" if @timeout_seconds && !@timeout_seconds.between?(1, 7 * 24 * 3600)
+
+        raw_steps = data["steps"]
+        unless raw_steps.is_a?(Array) && raw_steps.any?
+          @errors << "steps must be a non-empty list"
+          @steps = []
+          return
+        end
+        @errors << "too many steps (max #{MAX_STEPS})" if raw_steps.size > MAX_STEPS
+        @steps = raw_steps.each_with_index.filter_map { |s, i| build_step(s, i) }
+        ids = @steps.map(&:id)
+        dupes = ids.tally.select { |_, c| c > 1 }.keys
+        @errors << "duplicate step ids: #{dupes.join(", ")}" if dupes.any?
+        @steps.each do |s|
+          (s.depends_on - ids).each { |d| @errors << "step #{s.id} depends on unknown step #{d}" }
+          @errors << "step #{s.id} depends on itself" if s.depends_on.include?(s.id)
+          next unless s.condition
+
+          refs = Condition.parse(s.condition).step_refs
+          (refs - ids).each { |r| @errors << "step #{s.id} condition references unknown step #{r}" }
+          (refs - ancestors(s.id)).each { |r| @errors << "step #{s.id} condition references #{r}, which is not an ancestor" } if @errors.empty?
+        rescue Condition::SyntaxError => e
+          @errors << "step #{s.id} condition: #{e.message}"
+        end
+        @errors << "workflow contains a dependency cycle" if @errors.empty? && topological_order.size != @steps.size
+      end
+
+      def ancestors(id, seen = Set.new)
+        step = @steps.find { |s| s.id == id }
+        return seen unless step
+
+        step.depends_on.each { |d| ancestors(d, seen << d) unless seen.include?(d) }
+        seen.to_a
+      end
+
+      def build_step(raw, index)
+        unless raw.is_a?(Hash)
+          @errors << "step ##{index + 1} must be a mapping"
+          return nil
+        end
+        raw = raw.transform_keys(&:to_s)
+        allowed = %w[id type provider action command depends_on condition retry timeout_seconds required_role config integration]
+        unknown = raw.keys - allowed
+        @errors << "step #{raw["id"] || index + 1}: unknown keys #{unknown.join(", ")}" if unknown.any?
+
+        id = raw["id"].to_s
+        @errors << "step ##{index + 1}: id must match /\\A[a-z][a-z0-9_]{0,63}\\z/" unless id.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+        type = raw["type"].to_s
+        @errors << "step #{id}: unknown type #{type}" unless STEP_TYPES.include?(type)
+
+        case type
+        when "agent"
+          @errors << "step #{id}: unknown provider #{raw["provider"]}" unless @providers.include?(raw["provider"].to_s)
+          @errors << "step #{id}: action must be one of #{AGENT_ACTIONS.join(", ")}" unless AGENT_ACTIONS.include?(raw["action"].to_s)
+        when "command", "verification"
+          if raw["command"].is_a?(Array) || raw["command"].to_s.include?(" ")
+            @errors << "step #{id}: command must reference a catalog entry by name, not a shell string"
+          elsif !@catalog.names.include?(raw["command"].to_s)
+            @errors << "step #{id}: command #{raw["command"]} is not in the approved catalog"
+          end
+        when "external"
+          name = raw["integration"].to_s
+          unless (Agentboard.config.settings["integrations"] || {}).key?(name)
+            @errors << "step #{id}: integration #{name.inspect} is not configured under `integrations`"
+          end
+          if retry_policy = raw["retry"]
+            @errors << "step #{id}: external steps cannot be retried automatically" if retry_policy.is_a?(Hash) && retry_policy["max_attempts"].to_i > 1
+          end
+        when "human_approval"
+          role = (raw["required_role"] || "maintainer").to_s
+          @errors << "step #{id}: required_role must be maintainer or administrator" unless %w[maintainer administrator].include?(role)
+        end
+
+        retry_policy = raw["retry"]
+        if retry_policy
+          if retry_policy.is_a?(Hash)
+            retry_policy = retry_policy.transform_keys(&:to_s)
+            attempts = retry_policy["max_attempts"].to_i
+            @errors << "step #{id}: retry.max_attempts must be 1..#{MAX_ATTEMPTS}" unless attempts.between?(1, MAX_ATTEMPTS)
+            backoff = Array(retry_policy["backoff_seconds"])
+            @errors << "step #{id}: retry.backoff_seconds must be integers 0..3600" unless backoff.all? { |b| b.is_a?(Integer) && b.between?(0, 3600) }
+            bad = Array(retry_policy["retry_on"]).map(&:to_s) - RETRYABLE
+            @errors << "step #{id}: retry_on contains unsupported reasons #{bad.join(", ")}" if bad.any?
+            if %w[git_commit git_pull_request command].include?(type) && attempts > 1
+              @errors << "step #{id}: non-idempotent #{type} steps cannot be retried automatically"
+            end
+          else
+            @errors << "step #{id}: retry must be a mapping"
+          end
+        end
+
+        timeout = raw["timeout_seconds"]&.to_i
+        @errors << "step #{id}: timeout_seconds must be 1..#{MAX_TIMEOUT}" if timeout && !timeout.between?(1, MAX_TIMEOUT)
+        depends = Array(raw["depends_on"]).map(&:to_s)
+
+        Step.new(id: id, type: type, provider: raw["provider"]&.to_s, action: raw["action"]&.to_s, command: raw["command"]&.to_s,
+                 depends_on: depends, condition: raw["condition"]&.to_s, retry: retry_policy.is_a?(Hash) ? retry_policy : nil,
+                 timeout_seconds: timeout, required_role: raw["required_role"]&.to_s, config: raw["config"].is_a?(Hash) ? raw["config"] : nil,
+                 integration: raw["integration"]&.to_s)
+      end
+    end
+  end
+end

data/lib/agentboard/workflows.rb

@@ -0,0 +1,2 @@
+require "agentboard/workflows/condition"
+require "agentboard/workflows/definition"