agentboard 0.2.0

data/db/migrate/20261114000001_create_agentboard_core.rb

@@ -0,0 +1,144 @@
+# AgentBoard core schema (spec §23.1).
+#
+# Primary keys are application-generated UUIDv7 strings so the same schema works on
+# PostgreSQL and SQLite without extensions. Every table is prefixed `agentboard_`.
+class CreateAgentboardCore < ActiveRecord::Migration[7.2]
+  def change
+    create_table :agentboard_projects, id: :string, limit: 36 do |t|
+      t.string :key, null: false, limit: 16
+      t.string :name, null: false
+      t.string :root_path, null: false
+      t.string :repository_url
+      t.string :default_branch, null: false, default: "main"
+      t.json :settings, null: false, default: {}
+      t.integer :ticket_counter, null: false, default: 0
+      t.timestamps
+    end
+    add_index :agentboard_projects, :key, unique: true
+    add_index :agentboard_projects, :root_path, unique: true
+
+    create_table :agentboard_milestones, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :name, null: false
+      t.date :target_date
+      t.string :status, null: false, default: "open"
+      t.timestamps
+    end
+
+    create_table :agentboard_tickets, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.references :milestone, type: :string, foreign_key: { to_table: :agentboard_milestones }
+      t.references :parent, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.integer :number, null: false
+      t.string :title, null: false, limit: 255
+      t.text :description, null: false, default: ""
+      t.string :kind, null: false, default: "task"
+      t.string :status, null: false, default: "backlog"
+      t.integer :priority, null: false, default: 2
+      t.float :position, null: false, default: 0
+      t.json :labels, null: false, default: []
+      t.string :assignee_profile_id, limit: 36
+      t.string :created_by_id
+      t.text :blocked_reason
+      t.bigint :fencing_counter, null: false, default: 0
+      t.integer :lock_version, null: false, default: 0
+      t.datetime :completed_at
+      t.timestamps
+    end
+    add_index :agentboard_tickets, [ :project_id, :number ], unique: true
+    add_index :agentboard_tickets, [ :project_id, :status, :priority ]
+
+    create_table :agentboard_ticket_dependencies, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.references :depends_on_ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.string :kind, null: false, default: "blocks"
+      t.timestamps
+    end
+    add_index :agentboard_ticket_dependencies, [ :ticket_id, :depends_on_ticket_id, :kind ], unique: true, name: "index_agentboard_ticket_deps_unique"
+    add_check_constraint :agentboard_ticket_dependencies, "ticket_id <> depends_on_ticket_id", name: "agentboard_no_self_dependency"
+
+    create_table :agentboard_acceptance_criteria, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.integer :position, null: false
+      t.text :description, null: false
+      t.string :verification_kind, null: false, default: "manual"
+      t.string :state, null: false, default: "pending"
+      t.string :evidence_id, limit: 36
+      t.string :verified_by
+      t.datetime :verified_at
+      t.timestamps
+    end
+    add_index :agentboard_acceptance_criteria, [ :ticket_id, :position ], unique: true
+
+    create_table :agentboard_comments, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.string :actor_type, null: false
+      t.string :actor_id, null: false
+      t.string :actor_name
+      t.string :visibility, null: false, default: "team"
+      t.text :body, null: false
+      t.timestamps
+    end
+    add_index :agentboard_comments, [ :ticket_id, :created_at ]
+
+    create_table :agentboard_agent_profiles, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :provider_key, null: false
+      t.string :name, null: false
+      t.string :model
+      t.json :config, null: false, default: {}
+      t.json :permissions, null: false, default: {}
+      t.boolean :enabled, null: false, default: true
+      t.timestamps
+    end
+    add_index :agentboard_agent_profiles, [ :project_id, :name ], unique: true
+
+    create_table :agentboard_agent_sessions, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :provider_key, null: false
+      t.string :external_session_id
+      t.string :state, null: false, default: "active"
+      t.string :trust_level, null: false, default: "untrusted"
+      t.string :label
+      t.string :credential_digest
+      t.string :cwd
+      t.json :metadata, null: false, default: {}
+      t.datetime :last_seen_at
+      t.datetime :ended_at
+      t.timestamps
+    end
+    add_index :agentboard_agent_sessions, [ :project_id, :provider_key, :external_session_id ], unique: true,
+              where: "external_session_id IS NOT NULL", name: "index_agentboard_sessions_external_unique"
+    add_index :agentboard_agent_sessions, :credential_digest, unique: true, where: "credential_digest IS NOT NULL"
+
+    create_table :agentboard_session_ticket_links, id: :string, limit: 36 do |t|
+      t.references :agent_session, null: false, type: :string, foreign_key: { to_table: :agentboard_agent_sessions }
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.datetime :started_at, null: false
+      t.datetime :ended_at
+      t.string :source, null: false
+      t.string :confidence, null: false, default: "confirmed"
+      t.timestamps
+    end
+    add_index :agentboard_session_ticket_links, [ :agent_session_id, :ended_at ]
+    add_index :agentboard_session_ticket_links, :agent_session_id, unique: true, where: "ended_at IS NULL",
+              name: "index_agentboard_session_links_one_active"
+
+    create_table :agentboard_ticket_leases, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.references :agent_session, type: :string, foreign_key: { to_table: :agentboard_agent_sessions }
+      t.string :holder_label
+      t.string :token_digest, null: false
+      t.bigint :fencing_token, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :released_at
+      t.string :release_reason
+      t.timestamps
+    end
+    # Database-enforced exclusivity: at most one unreleased lease per ticket.
+    add_index :agentboard_ticket_leases, :ticket_id, unique: true, where: "released_at IS NULL",
+              name: "index_agentboard_leases_one_live_per_ticket"
+    add_index :agentboard_ticket_leases, :expires_at
+    add_index :agentboard_ticket_leases, :token_digest, unique: true
+  end
+end

data/db/migrate/20261114000002_create_agentboard_runtime.rb

@@ -0,0 +1,213 @@
+# Executions, workflows, verification, approvals and evidence (spec §23.1).
+class CreateAgentboardRuntime < ActiveRecord::Migration[7.2]
+  def change
+    create_table :agentboard_workflow_definitions, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :name, null: false
+      t.integer :version, null: false
+      t.json :definition, null: false
+      t.text :source_yaml
+      t.string :digest, null: false
+      t.timestamps
+    end
+    add_index :agentboard_workflow_definitions, [ :project_id, :name, :version ], unique: true, name: "index_agentboard_workflow_defs_unique"
+    add_index :agentboard_workflow_definitions, [ :project_id, :digest ]
+
+    create_table :agentboard_workflow_runs, id: :string, limit: 36 do |t|
+      t.references :workflow_definition, null: false, type: :string, foreign_key: { to_table: :agentboard_workflow_definitions }
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.string :status, null: false, default: "pending"
+      t.string :base_sha
+      t.string :worktree_path
+      t.string :branch
+      t.string :cancel_reason
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+    end
+    add_index :agentboard_workflow_runs, :status
+
+    create_table :agentboard_workflow_steps, id: :string, limit: 36 do |t|
+      t.references :workflow_run, null: false, type: :string, foreign_key: { to_table: :agentboard_workflow_runs }
+      t.string :step_key, null: false
+      t.string :step_type, null: false
+      t.string :status, null: false, default: "pending"
+      t.integer :attempt, null: false, default: 1
+      t.json :input, null: false, default: {}
+      t.json :output, null: false, default: {}
+      t.text :error
+      t.datetime :available_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.timestamps
+    end
+    add_index :agentboard_workflow_steps, [ :workflow_run_id, :step_key, :attempt ], unique: true, name: "index_agentboard_workflow_steps_unique"
+
+    create_table :agentboard_executions, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.references :agent_profile, type: :string, foreign_key: { to_table: :agentboard_agent_profiles }
+      t.references :agent_session, type: :string, foreign_key: { to_table: :agentboard_agent_sessions }
+      t.references :workflow_step, type: :string, foreign_key: { to_table: :agentboard_workflow_steps }
+      t.string :provider_key, null: false
+      t.string :action, null: false, default: "implement"
+      t.string :status, null: false, default: "queued"
+      t.integer :attempt, null: false, default: 1
+      t.string :base_sha
+      t.string :head_sha
+      t.string :branch
+      t.string :worktree_path
+      t.string :context_path
+      t.string :context_digest
+      t.string :log_path
+      t.integer :pid
+      t.integer :pgid
+      t.string :process_fingerprint
+      t.string :idempotency_key
+      t.integer :exit_code
+      t.string :failure_code
+      t.text :failure_message
+      t.text :summary
+      t.string :cancel_reason
+      t.datetime :cancel_requested_at
+      t.datetime :heartbeat_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.bigint :log_bytes, null: false, default: 0
+      t.boolean :log_truncated, null: false, default: false
+      t.json :metadata, null: false, default: {}
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+    end
+    add_index :agentboard_executions, [ :ticket_id, :created_at ]
+    add_index :agentboard_executions, [ :status, :created_at ]
+    add_index :agentboard_executions, [ :ticket_id, :attempt ], unique: true
+    add_index :agentboard_executions, :idempotency_key, unique: true, where: "idempotency_key IS NOT NULL"
+
+    create_table :agentboard_events, id: :string, limit: 36 do |t|
+      t.string :project_id, limit: 36
+      t.string :aggregate_type, null: false
+      t.string :aggregate_id, null: false
+      t.bigint :sequence, null: false
+      t.string :event_type, null: false
+      t.integer :schema_version, null: false, default: 1
+      t.string :source, null: false
+      t.string :provenance, null: false, default: "confirmed"
+      t.string :ticket_id, limit: 36
+      t.string :execution_id, limit: 36
+      t.string :session_id, limit: 36
+      t.string :actor_type
+      t.string :actor_id
+      t.string :dedupe_key
+      t.datetime :occurred_at, null: false
+      t.datetime :received_at, null: false
+      t.json :payload, null: false, default: {}
+      t.string :correlation_id, null: false
+      t.string :causation_id
+      t.timestamps
+    end
+    add_index :agentboard_events, [ :aggregate_type, :aggregate_id, :sequence ], unique: true, name: "index_agentboard_events_aggregate_seq"
+    add_index :agentboard_events, [ :project_id, :received_at ]
+    add_index :agentboard_events, :correlation_id
+    add_index :agentboard_events, [ :ticket_id, :occurred_at ]
+    add_index :agentboard_events, [ :execution_id, :sequence ]
+    add_index :agentboard_events, :dedupe_key, unique: true, where: "dedupe_key IS NOT NULL"
+
+    create_table :agentboard_outbox_messages, id: :string, limit: 36 do |t|
+      t.string :event_id, null: false, limit: 36
+      t.string :topic, null: false
+      t.string :state, null: false, default: "pending"
+      t.integer :attempts, null: false, default: 0
+      t.datetime :available_at, null: false
+      t.datetime :delivered_at
+      t.text :last_error
+      t.timestamps
+    end
+    add_index :agentboard_outbox_messages, [ :event_id, :topic ], unique: true
+    add_index :agentboard_outbox_messages, [ :state, :available_at ]
+
+    create_table :agentboard_artifacts, id: :string, limit: 36 do |t|
+      t.references :ticket, null: false, type: :string, foreign_key: { to_table: :agentboard_tickets }
+      t.references :execution, type: :string, foreign_key: { to_table: :agentboard_executions }
+      t.string :kind, null: false
+      t.string :uri, null: false
+      t.string :title
+      t.string :sha256
+      t.string :commit_sha
+      t.string :provenance, null: false, default: "confirmed"
+      t.json :metadata, null: false, default: {}
+      t.timestamps
+    end
+
+    create_table :agentboard_verification_results, id: :string, limit: 36 do |t|
+      t.references :execution, null: false, type: :string, foreign_key: { to_table: :agentboard_executions }
+      t.string :ticket_id, limit: 36
+      t.string :name, null: false
+      t.string :status, null: false, default: "running"
+      t.boolean :required, null: false, default: true
+      t.string :command_digest, null: false
+      t.string :commit_sha, null: false
+      t.integer :exit_code
+      t.string :log_artifact_id, limit: 36
+      t.text :output_excerpt
+      t.float :duration_seconds
+      t.datetime :started_at, null: false
+      t.datetime :finished_at
+      t.timestamps
+    end
+    add_index :agentboard_verification_results, [ :execution_id, :commit_sha ]
+    add_index :agentboard_verification_results, [ :ticket_id, :commit_sha ]
+
+    create_table :agentboard_approvals, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :ticket_id, limit: 36
+      t.references :execution, type: :string, foreign_key: { to_table: :agentboard_executions }
+      t.string :workflow_step_id, limit: 36
+      t.string :action_kind, null: false
+      t.string :action_digest, null: false
+      t.string :head_sha
+      t.json :action_payload, null: false, default: {}
+      t.text :reason
+      t.string :required_role, null: false, default: "maintainer"
+      t.string :requested_by, null: false
+      t.string :decision, null: false, default: "pending"
+      t.string :decided_by
+      t.text :decision_reason
+      t.datetime :expires_at
+      t.datetime :decided_at
+      t.timestamps
+    end
+    add_index :agentboard_approvals, [ :decision, :expires_at ]
+    add_index :agentboard_approvals, :ticket_id
+
+    create_table :agentboard_usage_records, id: :string, limit: 36 do |t|
+      t.references :execution, null: false, type: :string, foreign_key: { to_table: :agentboard_executions }
+      t.string :provider_key, null: false
+      t.string :metering_kind, null: false, default: "unknown"
+      t.bigint :input_tokens
+      t.bigint :output_tokens
+      t.decimal :reported_cost, precision: 12, scale: 6
+      t.string :currency
+      t.string :source, null: false
+      t.timestamps
+    end
+
+    create_table :agentboard_idempotency_keys, id: :string, limit: 36 do |t|
+      t.string :scope, null: false
+      t.string :key, null: false
+      t.string :request_digest, null: false
+      t.json :response, null: false, default: {}
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+    add_index :agentboard_idempotency_keys, [ :scope, :key ], unique: true
+
+    create_table :agentboard_repository_snapshots, id: :string, limit: 36 do |t|
+      t.references :project, null: false, type: :string, foreign_key: { to_table: :agentboard_projects }
+      t.string :commit_sha, null: false
+      t.json :metadata, null: false, default: {}
+      t.timestamps
+    end
+    add_index :agentboard_repository_snapshots, [ :project_id, :commit_sha ], unique: true
+  end
+end

data/db/migrate/20261115000001_create_agentboard_webhook_deliveries.rb

@@ -0,0 +1,18 @@
+# v0.2: Git provider webhooks (spec §29.3). Deliveries are recorded for idempotency and audit,
+# including rejected (forged) ones. Raw payloads are never stored — only a digest.
+class CreateAgentboardWebhookDeliveries < ActiveRecord::Migration[7.2]
+  def change
+    create_table :agentboard_webhook_deliveries, id: :string, limit: 36 do |t|
+      t.string :provider, null: false
+      t.string :delivery_id, null: false
+      t.string :event, null: false
+      t.boolean :signature_valid, null: false, default: false
+      t.string :payload_digest, null: false
+      t.string :status, null: false, default: "received"
+      t.text :detail
+      t.timestamps
+    end
+    add_index :agentboard_webhook_deliveries, [ :provider, :delivery_id ], unique: true, name: "index_agentboard_webhook_deliveries_unique"
+    add_index :agentboard_webhook_deliveries, :created_at
+  end
+end

data/exe/agentboard

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "agentboard/cli"
+Agentboard::CLI.start(ARGV)

data/lib/agentboard/agent_container.rb

@@ -0,0 +1,124 @@
+require "agentboard/container_sandbox"
+
+module Agentboard
+  # Runs provider agents inside OCI containers (security.sandbox: container, sandbox.agents: true).
+  #
+  # - The agent container is attached only to an *internal* network (no direct internet).
+  #   Its single route out is the egress proxy container, which allowlists provider APIs.
+  # - Mounts: the execution worktree and the repository's git directory, at their real host
+  #   paths (so `git commit` works). Nothing else from the host is visible.
+  # - Runs as the invoking UID, all capabilities dropped, no-new-privileges, CPU/memory/PID
+  #   limits, read-only root filesystem with a tmpfs home.
+  # - Credentials: only allowlisted variable *names* are forwarded (`-e NAME`), so values
+  #   never appear in process listings.
+  module AgentContainer
+    DEFAULT_EGRESS = {
+      "claude" => %w[api.anthropic.com:443 statsig.anthropic.com:443 sentry.io:443],
+      "codex" => %w[api.openai.com:443 chatgpt.com:443 auth.openai.com:443],
+      "fake" => []
+    }.freeze
+    PROXY_ALIAS = "agentboard-egress".freeze
+    PROXY_PORT = 3128
+
+    module_function
+
+    def settings = ContainerSandbox.settings
+    def runtime = settings["runtime"]
+    def enabled? = ContainerSandbox.enabled? && settings["agents"] == true
+
+    def image
+      settings["agent_image"].presence or raise Error.validation_failed("sandbox.agent_image must be set to run agents in containers (see `agentboard sandbox build`)")
+    end
+
+    def project_id = Digest::SHA256.hexdigest(Agentboard.config.root_path.to_s)[0, 10]
+    def network_name = "agentboard-#{project_id}-internal"
+    def proxy_name = "agentboard-#{project_id}-egress"
+
+    def egress_allowlist
+      (DEFAULT_EGRESS.values.flatten + Array(settings["egress_allow"])).map(&:to_s).uniq.sort
+    end
+
+    # Builds the docker argv that wraps a provider LaunchSpec.
+    def wrap(spec, execution:, name:)
+      worktree = File.realpath(spec.chdir.to_s)
+      git_common = git_common_dir(worktree)
+      argv = [ runtime, "run", "--rm", "-i", "--init", "--name", name,
+               "--label", "agentboard.execution=#{execution.id}",
+               "--network", network_name,
+               "--memory", settings["memory"].to_s, "--cpus", settings["cpus"].to_s, "--pids-limit", settings["pids_limit"].to_i.to_s,
+               "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--read-only",
+               "--tmpfs", "/tmp:rw,exec,size=1g", "--user", "#{::Process.uid}:#{::Process.gid}",
+               "-v", "#{worktree}:#{worktree}:rw", "-v", "#{git_common}:#{git_common}:rw", "-w", worktree,
+               "-e", "HOME=/tmp/agent-home", "-e", "AGENTBOARD_EXECUTION_ID=#{execution.id}", "-e", "AGENTBOARD_ISOLATION=container",
+               "-e", "HTTPS_PROXY=http://#{PROXY_ALIAS}:#{PROXY_PORT}", "-e", "HTTP_PROXY=http://#{PROXY_ALIAS}:#{PROXY_PORT}",
+               "-e", "NO_PROXY=localhost,127.0.0.1" ]
+      if (dir = settings["claude_config_dir"].presence)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        argv += [ "-v", "#{File.realpath(dir)}:/tmp/agent-home/.claude:rw", "-e", "CLAUDE_CONFIG_DIR=/tmp/agent-home/.claude" ]
+      end
+      Array(spec.mounts).each { |m| real = File.realpath(m); argv += [ "-v", "#{real}:#{real}:ro" ] }
+      spec.env.to_h.each { |k, v| argv += [ "-e", "#{k}=#{v}" ] if k.to_s.match?(/\A[A-Z_][A-Z0-9_]*\z/) && !secret_name?(k) }
+      forwarded_credentials(spec).each { |k| argv += [ "-e", k ] }
+      cli_env(spec).each_key { |k| argv += [ "-e", k ] unless argv.include?(k) }
+      argv + [ image ] + spec.argv
+    end
+
+    # Names only; docker reads the values from its own environment.
+    def forwarded_credentials(spec)
+      allowed = Array(settings["credential_env"]).map(&:to_s)
+      (Array(spec.passthrough_env).map(&:to_s) & (allowed.presence || Array(spec.passthrough_env).map(&:to_s))).select { |k| ENV[k].present? }
+    end
+
+    # Values for aliased credentials, placed in the docker CLI's own environment (never argv).
+    def cli_env(spec)
+      allowed = Array(settings["credential_env"]).map(&:to_s)
+      Array(spec.credential_aliases).each_with_object({}) do |(name, source), env|
+        next if allowed.any? && !allowed.include?(source.to_s)
+
+        env[name.to_s] = ENV[source.to_s] if ENV[source.to_s].present?
+      end
+    end
+
+    def secret_name?(name) = name.to_s.match?(/KEY|TOKEN|SECRET|PASSWORD/i)
+
+    def git_common_dir(worktree)
+      out, _e, st = Open3.capture3("git", "rev-parse", "--git-common-dir", chdir: worktree)
+      raise Error.workspace_conflict("worktree has no git directory") unless st.success?
+
+      File.realpath(File.expand_path(out.strip, worktree))
+    end
+
+    # Idempotently creates the internal network and the egress proxy container.
+    def ensure_network!
+      unless system(runtime, "network", "inspect", network_name, out: File::NULL, err: File::NULL)
+        run!("network", "create", "--internal", "--label", "agentboard.project=#{project_id}", network_name)
+      end
+      allow = egress_allowlist.join(",")
+      digest = Digest::SHA256.hexdigest(allow)[0, 12]
+      out, _e, st = Open3.capture3(runtime, "inspect", "--format", "{{.State.Running}} {{index .Config.Labels \"agentboard.allow\"}}", proxy_name)
+      running, label = out.split
+      return if st.success? && running == "true" && label == digest
+
+      Open3.capture3(runtime, "rm", "-f", proxy_name)
+      proxy_script = File.expand_path("egress_proxy.rb", __dir__)
+      run!("run", "-d", "--name", proxy_name, "--restart", "unless-stopped", "--label", "agentboard.allow=#{digest}",
+           "--network", network_name, "--network-alias", PROXY_ALIAS, "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
+           "--read-only", "--memory", "128m", "-e", "EGRESS_ALLOW=#{allow}",
+           "-v", "#{proxy_script}:/egress_proxy.rb:ro", settings["proxy_image"].presence || "ruby:3.4-alpine", "ruby", "/egress_proxy.rb", PROXY_PORT.to_s)
+      run!("network", "connect", "bridge", proxy_name)
+    end
+
+    def remove(name)
+      Open3.capture3(runtime, "rm", "-f", name) if name.present?
+    rescue StandardError
+      nil
+    end
+
+    def run!(*args)
+      out, err, st = Open3.capture3(runtime, *args)
+      raise Error.provider_unavailable("#{runtime} #{args.first} failed: #{Redactor.redact(err.presence || out)[0, 300]}") unless st.success?
+
+      out
+    end
+  end
+end

data/lib/agentboard/authorization.rb

@@ -0,0 +1,58 @@
+module Agentboard
+  # Role-based permissions (spec §14). Agents receive narrowly scoped permissions and
+  # can never satisfy human-only guards (approvals, reopen, completion override).
+  module Authorization
+    ROLES = %w[viewer developer maintainer administrator].freeze
+
+    PERMISSIONS = {
+      "ticket.read" => %w[viewer developer maintainer administrator agent],
+      "ticket.write" => %w[developer maintainer administrator],
+      "ticket.transition" => %w[developer maintainer administrator agent],
+      "ticket.comment" => %w[developer maintainer administrator agent],
+      "ticket.claim" => %w[developer maintainer administrator agent],
+      "ticket.complete" => %w[maintainer administrator],
+      "ticket.reopen" => %w[maintainer administrator],
+      "ticket.cancel" => %w[developer maintainer administrator],
+      "execution.start" => %w[developer maintainer administrator],
+      "execution.cancel" => %w[developer maintainer administrator],
+      "approval.request" => %w[developer maintainer administrator agent],
+      "approval.decide" => %w[maintainer administrator],
+      "workflow.manage" => %w[maintainer administrator],
+      "session.manage" => %w[maintainer administrator],
+      "settings.manage" => %w[administrator]
+    }.freeze
+
+    # Transitions an agent identity may never perform on its own.
+    HUMAN_ONLY_TRANSITIONS = %w[done reopened cancelled backlog].freeze
+
+    # An actor is anything responding to #role, #type ("human"/"agent"/"system") and #id.
+    Actor = Struct.new(:type, :id, :role, :name, keyword_init: true) do
+      def agent? = type == "agent"
+      def human? = type == "human"
+      def system? = type == "system"
+      def label = name || "#{type}:#{id}"
+    end
+
+    module_function
+
+    def system_actor = Actor.new(type: "system", id: "agentboard", role: "administrator", name: "AgentBoard")
+    def local_human(name = ENV["USER"] || "local") = Actor.new(type: "human", id: name, role: "administrator", name: name)
+
+    def agent_actor(session_id, name: nil)
+      Actor.new(type: "agent", id: session_id.to_s, role: "agent", name: name || "agent:#{session_id.to_s[0, 8]}")
+    end
+
+    def allowed?(actor, permission)
+      return false unless actor
+      return true if actor.system?
+
+      PERMISSIONS.fetch(permission) { raise ArgumentError, "unknown permission #{permission}" }.include?(actor.role.to_s)
+    end
+
+    def authorize!(actor, permission)
+      return true if allowed?(actor, permission)
+
+      raise Error.forbidden("#{actor&.label || "anonymous"} is not allowed to #{permission}", permission: permission)
+    end
+  end
+end

data/lib/agentboard/capture/middleware.rb

@@ -0,0 +1,54 @@
+module Agentboard
+  module Capture
+    # Injects the capture widget into the host app's HTML pages (never into AgentBoard's own
+    # dashboard) and records which templates rendered the page.
+    class Middleware
+      MAX_BODY = 5 * 1024 * 1024
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless Capture.enabled_for_env?
+        return @app.call(env) if env["PATH_INFO"].to_s.start_with?(Capture.mount_path + "/") || env["PATH_INFO"] == Capture.mount_path
+
+        Thread.current[:agentboard_capture_collector] = Collector.new
+        status, headers, body = @app.call(env)
+        inject(env, status, headers, body)
+      ensure
+        Thread.current[:agentboard_capture_collector] = nil
+      end
+
+      private
+
+      def inject(env, status, headers, body)
+        type = headers["content-type"] || headers["Content-Type"]
+        return [ status, headers, body ] unless status == 200 && type.to_s.include?("text/html")
+        return [ status, headers, body ] if env["HTTP_TURBO_FRAME"] || headers["content-disposition"].to_s.include?("attachment")
+
+        html = +""
+        body.each { |part| html << part }
+        body.close if body.respond_to?(:close)
+        index = html.bytesize <= MAX_BODY ? html.rindex("</body>") : nil
+        return [ status, headers, [ html ] ] unless index
+
+        html.insert(index, tag(env))
+        headers.delete("content-length")
+        headers.delete("Content-Length")
+        [ status, headers, [ html ] ]
+      end
+
+      def tag(env)
+        params = env["action_dispatch.request.path_parameters"] || {}
+        data = {
+          endpoint: "#{Capture.mount_path}/captures", dashboard: Capture.mount_path,
+          route: [ params[:controller], params[:action] ].compact.join("#").presence,
+          templates: Capture.collector&.templates || [], screenshots: Capture.screenshots?, version: Agentboard::VERSION
+        }
+        src = "#{Capture.mount_path}/assets/capture.js?v=#{AssetsController.fingerprint("capture.js")}"
+        %(<script src="#{src}" data-agentboard-capture="#{ERB::Util.html_escape(JSON.generate(data))}" defer></script>)
+      end
+    end
+  end
+end