agentboard 0.2.0

data/app/services/agentboard/doctor.rb

@@ -0,0 +1,133 @@
+module Agentboard
+  # Diagnostics shared by `agentboard doctor` and the Settings page (spec §31.3).
+  class Doctor
+    Check = Struct.new(:name, :status, :detail, keyword_init: true) # status: ok | warn | fail
+
+    def initialize(root:)
+      @root = root.to_s
+    end
+
+    def checks
+      [ ruby_check, git_check, worktree_check, database_check, migrations_check, mount_check, config_check,
+        daemon_check, mcp_check, sandbox_check, edition_check, *Extensions.run(:doctor_checks).flatten.compact, *provider_checks ]
+    end
+
+    def ok? = checks.none? { |c| c.status == "fail" }
+
+    private
+
+    def edition_check
+      ext = Extensions.extensions.values
+      if ext.empty?
+        Check.new(name: "Edition", status: "ok", detail: "Community (MIT) — Pro features: #{Extensions::FEATURES.keys.join(", ")}")
+      else
+        Check.new(name: "Edition", status: "ok", detail: ext.map { |e| "#{e.name} #{e.version} (#{e.enabled_features.join(", ").presence || "no licensed features"})" }.join("; "))
+      end
+    end
+
+    def ruby_check
+      ok = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
+      Check.new(name: "Ruby", status: ok ? "ok" : "fail", detail: "#{RUBY_VERSION} (requires >= 3.3)")
+    end
+
+    def git_check
+      out, _e, st = Open3.capture3("git", "--version")
+      repo = Git::Repository.new(@root)
+      return Check.new(name: "Git", status: "fail", detail: "git not available") unless st.success?
+      return Check.new(name: "Git", status: "fail", detail: "#{@root} is not a Git repository") unless repo.repository?
+
+      Check.new(name: "Git", status: "ok", detail: "#{out.strip} · default branch #{repo.default_branch}")
+    rescue Errno::ENOENT
+      Check.new(name: "Git", status: "fail", detail: "git not found on PATH")
+    end
+
+    def worktree_check
+      out, _e, st = Open3.capture3("git", "worktree", "list", chdir: @root)
+      Check.new(name: "Git worktrees", status: st.success? ? "ok" : "fail", detail: st.success? ? "#{out.lines.size} worktree(s)" : "git worktree unsupported")
+    rescue Errno::ENOENT
+      Check.new(name: "Git worktrees", status: "fail", detail: "git not found")
+    end
+
+    def database_check
+      adapter = ActiveRecord::Base.connection_db_config.adapter
+      status = adapter.include?("postgres") ? "ok" : "warn"
+      detail = adapter.include?("sqlite") ? "#{adapter} — single-user development mode (PostgreSQL recommended for concurrent leases)" : adapter
+      Check.new(name: "Database", status: status, detail: detail)
+    rescue StandardError => e
+      Check.new(name: "Database", status: "fail", detail: e.class.name)
+    end
+
+    def migrations_check
+      missing = %w[agentboard_tickets agentboard_executions agentboard_events].reject { |t| ActiveRecord::Base.connection.table_exists?(t) }
+      if missing.any?
+        Check.new(name: "Migrations", status: "fail", detail: "missing tables: #{missing.join(", ")} — run bin/rails db:migrate")
+      else
+        Check.new(name: "Migrations", status: "ok", detail: "AgentBoard tables present")
+      end
+    rescue StandardError => e
+      Check.new(name: "Migrations", status: "fail", detail: e.class.name)
+    end
+
+    def mount_check
+      mounted = Rails.application.routes.routes.any? { |r| r.app.respond_to?(:app) && r.app.app == Agentboard::Engine }
+      Check.new(name: "Dashboard mount", status: mounted ? "ok" : "warn",
+                detail: mounted ? "mounted (development only by default)" : "Agentboard::Engine is not mounted in config/routes.rb")
+    rescue StandardError
+      Check.new(name: "Dashboard mount", status: "warn", detail: "could not inspect routes")
+    end
+
+    def config_check
+      files = Agentboard.config.loaded_files
+      Check.new(name: "Configuration", status: files.any? ? "ok" : "warn",
+                detail: files.any? ? files.map { |f| f.delete_prefix(@root + "/") }.join(", ") : "no config file found — run `agentboard init`")
+    end
+
+    def daemon_check
+      st = Runtime::DaemonControl.status
+      if st[:running]
+        Check.new(name: "Runtime daemon", status: "ok", detail: "pid #{st[:pid]}, #{st.dig(:health, "active")} active")
+      else
+        Check.new(name: "Runtime daemon", status: "warn", detail: st[:stale_pid_file] ? "stale PID file; daemon not running" : "not running — `agentboard daemon start`")
+      end
+    end
+
+    def mcp_check
+      require "mcp"
+      Check.new(name: "MCP server", status: "ok", detail: "mcp gem #{Gem.loaded_specs["mcp"]&.version} · stdio transport")
+    rescue LoadError
+      Check.new(name: "MCP server", status: "fail", detail: "mcp gem not available")
+    end
+
+    def sandbox_check
+      sec = Agentboard.config.security
+      if AgentContainer.enabled?
+        return Check.new(name: "Execution isolation", status: "fail", detail: "sandbox.agents is on but #{AgentContainer.runtime} is not running") unless ContainerSandbox.available?
+        return Check.new(name: "Execution isolation", status: "fail", detail: "sandbox.agent_image is not set (agentboard sandbox build)") if ContainerSandbox.settings["agent_image"].blank?
+
+        return Check.new(name: "Execution isolation", status: "ok",
+                         detail: "agents in containers (#{ContainerSandbox.settings["agent_image"]}), internal network, egress: #{AgentContainer.egress_allowlist.size} allowed endpoints")
+      end
+      if sec["trusted_local_execution"] && sec["sandbox"] != "container"
+        Check.new(name: "Execution isolation", status: "warn", detail: "trusted local subprocesses (worktrees are not sandboxes)")
+      elsif sec["sandbox"] == "container"
+        if ContainerSandbox.available?
+          Check.new(name: "Execution isolation", status: "ok", detail: "verification runs in #{ContainerSandbox.settings["runtime"]} (network #{ContainerSandbox.settings["network"]}); agents require trusted_local_execution")
+        else
+          Check.new(name: "Execution isolation", status: "fail", detail: "sandbox: container but #{ContainerSandbox.settings["runtime"]} is not running")
+        end
+      else
+        Check.new(name: "Execution isolation", status: "ok", detail: "active execution of real agents disabled until trusted_local_execution is enabled")
+      end
+    end
+
+    def provider_checks
+      Providers.registry.all.reject { |p| p.key == "fake" }.map do |p|
+        probe = p.probe
+        status = !probe.installed ? "warn" : (probe.supports?(:active_execution) ? "ok" : "warn")
+        caps = probe.supported_capabilities.map(&:to_s).join(", ")
+        Check.new(name: "Provider: #{p.display_name}", status: status,
+                  detail: probe.installed ? "#{probe.version} · #{probe.validation} · #{caps.presence || "no capabilities"}" : "not installed")
+      end
+    end
+  end
+end

data/app/services/agentboard/event_store.rb

@@ -0,0 +1,88 @@
+module Agentboard
+  # Appends events and their outbox messages in the caller's transaction, giving the
+  # transactional state-change + outbox guarantee (spec §11). Consumers must be idempotent;
+  # delivery is at-least-once, never exactly-once.
+  module EventStore
+    DEFAULT_TOPICS = %w[projections].freeze
+    MAX_PAYLOAD_BYTES = 64 * 1024
+
+    class Duplicate < StandardError
+      attr_reader :event
+      def initialize(event) = (@event = event; super("duplicate event #{event.id}"))
+    end
+
+    module_function
+
+    # Returns the persisted Event. With a dedupe_key, a replay returns the original event
+    # and does not insert a second row (raises Duplicate when raise_on_duplicate).
+    def append!(type:, aggregate:, source: "agentboard", provenance: "confirmed", payload: {},
+                actor: nil, project: nil, ticket: nil, execution: nil, session: nil,
+                correlation_id: nil, causation_id: nil, dedupe_key: nil, occurred_at: nil,
+                topics: DEFAULT_TOPICS, raise_on_duplicate: false, event_id: nil)
+      if dedupe_key && (existing = Event.find_by(dedupe_key: dedupe_key))
+        raise Duplicate, existing if raise_on_duplicate
+
+        return existing
+      end
+
+      aggregate_type, aggregate_id = resolve_aggregate(aggregate)
+      project_id = project&.id || ticket&.project_id || (aggregate.respond_to?(:project_id) && aggregate.project_id) || nil
+      safe_payload = bounded(Redactor.redact_value(deep_stringify(payload)))
+      now = Time.current
+
+      attempts = 0
+      begin
+        attempts += 1
+        Event.transaction(requires_new: true) do
+          sequence = Event.where(aggregate_type: aggregate_type, aggregate_id: aggregate_id).maximum(:sequence).to_i + 1
+          event = Event.create!(
+            id: event_id || Ids.uuid, project_id: project_id, aggregate_type: aggregate_type, aggregate_id: aggregate_id,
+            sequence: sequence, event_type: type, schema_version: EventSchema.current_version(type), source: source, provenance: provenance,
+            ticket_id: ticket&.id || (aggregate.is_a?(Ticket) ? aggregate.id : nil),
+            execution_id: execution&.id || (aggregate.is_a?(Execution) ? aggregate.id : nil),
+            session_id: session&.id, actor_type: actor&.type, actor_id: actor&.id,
+            dedupe_key: dedupe_key, occurred_at: occurred_at || now, received_at: now, payload: safe_payload,
+            correlation_id: correlation_id || Current.correlation_id || Ids.correlation, causation_id: causation_id
+          )
+          Array(topics).each do |topic|
+            OutboxMessage.create!(event_id: event.id, topic: topic, state: "pending", available_at: now)
+          end
+          event
+        end
+      rescue ActiveRecord::RecordNotUnique => e
+        if dedupe_key && (existing = Event.find_by(dedupe_key: dedupe_key))
+          raise Duplicate, existing if raise_on_duplicate
+
+          return existing
+        end
+        retry if attempts < 5
+        raise e
+      end
+    end
+
+    def resolve_aggregate(aggregate)
+      case aggregate
+      when Array then aggregate.map(&:to_s)
+      when ActiveRecord::Base then [ aggregate.class.name.demodulize.underscore, aggregate.id.to_s ]
+      else raise ArgumentError, "aggregate must be a record or [type, id]"
+      end
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [ k.to_s, deep_stringify(v) ] }
+      when Array then value.map { |v| deep_stringify(v) }
+      when Time, DateTime, ActiveSupport::TimeWithZone then value.utc.iso8601(3)
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    def bounded(payload)
+      json = payload.to_json
+      return payload if json.bytesize <= MAX_PAYLOAD_BYTES
+
+      { "truncated" => true, "original_bytes" => json.bytesize, "excerpt" => json.byteslice(0, 4096).scrub }
+    end
+  end
+end

data/app/services/agentboard/evidence.rb

@@ -0,0 +1,52 @@
+module Agentboard
+  # Resolves the code state a ticket is currently judged against, and records evidence
+  # artifacts with explicit provenance.
+  module Evidence
+    module_function
+
+    # The head commit is the most recent *verified-in-repo* commit evidence: execution head
+    # or attached commit artifact. Agent-claimed SHAs that aren't in the repository don't count.
+    def head_sha(ticket)
+      candidates = []
+      ticket.executions.where.not(head_sha: nil).where.not(action: "verify").limit(5).each { |e| candidates << [ e.finished_at || e.updated_at, e.head_sha ] }
+      ticket.artifacts.where(kind: "commit").limit(20).select { |a| a.metadata["verified_in_repo"] }.each { |a| candidates << [ a.created_at, a.commit_sha ] }
+      candidates.compact.max_by { |(t, _)| t.to_f }&.last
+    end
+
+    def attach_commit!(ticket:, commit_sha:, actor:, execution: nil, provenance: nil, session: nil)
+      sha = commit_sha.to_s.strip.downcase
+      raise Error.validation_failed("commit_sha must be a 7-64 character hex string") unless sha.match?(/\A[0-9a-f]{7,64}\z/)
+
+      repo = ticket.project.repository
+      full = repo.resolve_commit(sha)
+      verified = full.present?
+      Artifact.transaction do
+        artifact = ticket.artifacts.create!(
+          execution: execution, kind: "commit", uri: "git:#{full || sha}", commit_sha: full || sha, title: (verified ? repo.commit_subject(full) : nil),
+          provenance: provenance || (verified ? "git_observed" : (actor.agent? ? "provider_reported" : "confirmed")),
+          metadata: { verified_in_repo: verified, attached_by: actor.label }
+        )
+        EventStore.append!(type: "git.commit_attached", aggregate: ticket, ticket: ticket, actor: actor, session: session,
+                           provenance: artifact.provenance, payload: { artifact_id: artifact.id, commit_sha: artifact.commit_sha, verified_in_repo: verified })
+        artifact
+      end
+    end
+
+    def attach_artifact!(ticket:, actor:, kind:, uri:, title: nil, metadata: {}, execution: nil, session: nil)
+      raise Error.validation_failed("Unknown artifact kind #{kind}") unless Artifact::KINDS.include?(kind.to_s)
+      raise Error.validation_failed("Artifacts of kind commit must use attach_commit") if kind.to_s == "commit"
+      if uri.to_s.match?(/\A(?:javascript|data):/i)
+        raise Error.validation_failed("Unsupported URI scheme")
+      end
+
+      Artifact.transaction do
+        artifact = ticket.artifacts.create!(execution: execution, kind: kind, uri: uri.to_s[0, 2000], title: title&.to_s&.[](0, 255),
+                                            provenance: actor.agent? ? "provider_reported" : "confirmed",
+                                            metadata: Redactor.redact_value(metadata.to_h))
+        EventStore.append!(type: "ticket.artifact_attached", aggregate: ticket, ticket: ticket, actor: actor, session: session,
+                           provenance: artifact.provenance, payload: { artifact_id: artifact.id, kind: kind, uri: artifact.uri })
+        artifact
+      end
+    end
+  end
+end

data/app/services/agentboard/executions.rb

@@ -0,0 +1,198 @@
+module Agentboard
+  # Execution lifecycle operations shared by the dashboard, CLI, IPC and workflow engine.
+  # The database is the source of truth; the runtime daemon claims queued rows.
+  module Executions
+    RUNNABLE_TICKET_STATES = %w[ready claimed in_progress testing].freeze
+
+    module_function
+
+    def enqueue!(ticket:, provider_key:, actor:, action: "implement", profile: nil, workflow_step: nil,
+                 idempotency_key: nil, metadata: {}, correlation_id: nil)
+      Authorization.authorize!(actor, "execution.start") unless actor.system?
+      request = { ticket_id: ticket.id, provider_key: provider_key.to_s, action: action, step: workflow_step&.id }
+      response = Idempotency.call(scope: "execution.enqueue", key: idempotency_key, request: request) do
+        execution = create_queued!(ticket: ticket, provider_key: provider_key.to_s, actor: actor, action: action, profile: profile,
+                                   workflow_step: workflow_step, idempotency_key: idempotency_key, metadata: metadata, correlation_id: correlation_id)
+        { "execution_id" => execution.id, "status" => execution.status }
+      end
+      Execution.find(response["execution_id"])
+    end
+
+    def create_queued!(ticket:, provider_key:, actor:, action:, profile:, workflow_step:, idempotency_key:, metadata:, correlation_id:)
+      provider = Providers.registry.fetch(provider_key)
+      unless Agentboard.config.provider_enabled?(provider_key)
+        raise Error.policy_denied("Provider #{provider_key} is disabled in configuration")
+      end
+      if Agentboard.config.provider_settings(provider_key)["active"] == false
+        raise Error.policy_denied("Active execution is disabled for #{provider_key}")
+      end
+      probe = provider.probe
+      raise Error.provider_unavailable("#{provider.display_name} is not installed") unless probe.installed || AgentContainer.enabled?
+      unless probe.supports?(:active_execution) || (AgentContainer.enabled? && !probe.installed)
+        raise Error.capability_unavailable("#{provider.display_name} #{probe.version} cannot run active executions: #{probe.diagnostics.first}")
+      end
+      enforce_isolation_policy!(provider_key)
+
+      profile ||= AgentProfile.default_for(ticket.project, provider_key)
+      Execution.transaction do
+        ticket.lock!
+        unless RUNNABLE_TICKET_STATES.include?(ticket.status) || (workflow_step && ticket.status == "review")
+          raise Error.invalid_transition("#{ticket.key} is #{ticket.status}; executions need a ready or in-flight ticket")
+        end
+        raise Error.policy_denied("#{ticket.key} has unfinished dependencies") unless ticket.dependencies_satisfied?
+        if (running = ticket.executions.active.first) && workflow_step.nil?
+          raise Error.workspace_conflict("#{ticket.key} already has an active execution (#{running.label})")
+        end
+
+        session = AgentSession.create!(project: ticket.project, provider_key: provider_key, trust_level: "launched",
+                                       label: "#{provider.display_name} · #{ticket.key}", state: "active", last_seen_at: Time.current)
+        acquire_lease_for!(ticket, session, actor)
+
+        execution = Execution.create!(
+          ticket: ticket, agent_profile: profile, agent_session: session, workflow_step: workflow_step,
+          provider_key: provider_key, action: action, status: "queued", attempt: Execution.next_attempt_for(ticket),
+          idempotency_key: idempotency_key,
+          metadata: metadata.to_h.merge("requested_by" => actor.label, "probe_version" => probe.version,
+                                        "isolation" => AgentContainer.enabled? ? "container" : "local")
+        )
+        EventStore.append!(type: "agent.execution.queued", aggregate: execution, ticket: ticket, execution: execution, session: session,
+                           actor: actor, correlation_id: correlation_id,
+                           payload: { provider: provider_key, action: action, attempt: execution.attempt, profile: profile.name })
+        execution
+      end
+    end
+
+    # Spec §35.2 recommended default: trusted local subprocess execution is opt-in; untrusted
+    # work requires a container sandbox. The built-in fake provider is always allowed.
+    def enforce_isolation_policy!(provider_key)
+      return if provider_key.to_s == "fake"
+
+      sec = Agentboard.config.security
+      if AgentContainer.enabled?
+        raise Error.capability_unavailable("sandbox.agents is on but #{AgentContainer.runtime} is not running") unless ContainerSandbox.available?
+
+        AgentContainer.image # validates configuration
+        return
+      end
+      return if sec["trusted_local_execution"]
+
+      if sec["sandbox"].to_s == "container"
+        raise Error.capability_unavailable("Set sandbox.agents: true (with sandbox.agent_image) to run agents in containers, " \
+                                           "or security.trusted_local_execution: true to run them as trusted local subprocesses")
+      end
+      raise Error.policy_denied("Active execution requires security.trusted_local_execution: true (agents run as your user; worktrees are not sandboxes)")
+    end
+
+    def acquire_lease_for!(ticket, session, actor)
+      LeaseService.expire_stale!(ticket)
+      live = ticket.leases.live.first
+      if live
+        if live.agent_session_id && live.agent_session&.trust_level != "launched"
+          raise Error.lease_conflict("#{ticket.key} is leased by #{live.holder_label}")
+        end
+        if live.agent_session&.trust_level == "launched" && live.agent_session.executions.active.exists?
+          raise Error.lease_conflict("#{ticket.key} is leased by a running execution")
+        end
+
+        # Human-held or finished-runtime lease: hand over to this execution's session.
+        live.update!(agent_session: session, holder_label: session.display_name,
+                     expires_at: Time.current + Agentboard.config.runtime["execution_timeout_seconds"].to_i + 300)
+      elsif ticket.status == "ready"
+        claim = LeaseService.claim!(ticket: ticket, actor: Authorization.system_actor, session: session,
+                                    lease_seconds: Agentboard.config.leases["max_seconds"])
+        claim.lease.update!(expires_at: Time.current + Agentboard.config.runtime["execution_timeout_seconds"].to_i + 300)
+      else
+        fencing = ticket.fencing_counter + 1
+        ticket.leases.create!(agent_session: session, holder_label: session.display_name, token_digest: Ids.digest(Ids.token),
+                              fencing_token: fencing, expires_at: Time.current + Agentboard.config.runtime["execution_timeout_seconds"].to_i + 300)
+        ticket.update!(fencing_counter: fencing)
+      end
+    end
+
+    def transition!(execution, to, **attrs)
+      Execution.transaction do
+        execution.lock!
+        from = execution.status
+        return execution if from == to.to_s
+
+        StateMachines::Execution.assert!(from, to)
+        now = Time.current
+        updates = attrs.merge(status: to.to_s)
+        updates[:started_at] ||= now if to.to_s == "running" && execution.started_at.nil?
+        updates[:finished_at] = now if StateMachines::Execution.terminal?(to)
+        execution.update!(updates)
+        EventStore.append!(type: "agent.execution.#{to}", aggregate: execution, ticket: execution.ticket, execution: execution,
+                           session: execution.agent_session, actor: Authorization.system_actor,
+                           payload: { from: from, to: to.to_s, exit_code: attrs[:exit_code], failure_code: attrs[:failure_code],
+                                      reason: attrs[:failure_message] || attrs[:cancel_reason] }.compact)
+        if StateMachines::Execution.terminal?(to)
+          execution.agent_session&.update!(state: "ended", ended_at: now)
+          WorkflowEngine.step_execution_finished(execution) if execution.workflow_step_id
+        end
+        execution
+      end
+    end
+
+    def request_cancel!(execution:, actor:, reason: "cancelled by user")
+      Authorization.authorize!(actor, "execution.cancel") unless actor.system?
+      Execution.transaction do
+        execution.lock!
+        return execution if execution.terminal?
+
+        execution.update!(cancel_requested_at: Time.current, cancel_reason: reason.to_s[0, 500])
+        EventStore.append!(type: "agent.execution.cancel_requested", aggregate: execution, ticket: execution.ticket, execution: execution,
+                           actor: actor, payload: { reason: reason })
+        # Not yet picked up by the runtime: cancel immediately.
+        transition!(execution, "cancelled", cancel_reason: reason) if execution.status == "queued"
+      end
+      execution.reload
+    end
+
+    # Retries create a new attempt; history is preserved (spec §4).
+    def retry!(execution:, actor:)
+      raise Error.invalid_transition("Only finished executions can be retried") unless execution.terminal?
+
+      enqueue!(ticket: execution.ticket, provider_key: execution.provider_key, actor: actor, action: execution.action,
+               profile: execution.agent_profile, metadata: { "retry_of" => execution.id, "scenario" => execution.metadata["scenario"] }.compact)
+    end
+
+    # Resumes the provider session of a finished attempt as a new attempt in the same worktree.
+    def resume!(execution:, actor:, message: "Continue the task.")
+      raise Error.invalid_transition("Only finished executions can be resumed") unless execution.terminal?
+
+      provider = Providers.registry.fetch(execution.provider_key)
+      sid = execution.metadata["provider_session_id"]
+      raise UnsupportedCapability.new(:session_resume, provider: execution.provider_key) unless sid && provider.supports?(:session_resume)
+      raise Error.workspace_conflict("The worktree of that attempt no longer exists") unless execution.worktree_path && File.directory?(execution.worktree_path)
+
+      enqueue!(ticket: execution.ticket, provider_key: execution.provider_key, action: execution.action, actor: actor, profile: execution.agent_profile,
+               metadata: { "resume_of" => execution.id, "provider_session_id" => sid, "resume_message" => message.to_s[0, 4000] })
+    end
+
+    # Persists a provider-normalized event with provider_reported provenance.
+    def record_provider_event!(execution, normalized)
+      payload = normalized.payload.to_h
+      if (sid = normalized.external_session_id).present? && execution.metadata["provider_session_id"] != sid
+        execution.update_columns(metadata: execution.metadata.merge("provider_session_id" => sid.to_s[0, 128]))
+        session = execution.agent_session
+        if session && session.external_session_id.nil?
+          session.update_columns(external_session_id: sid.to_s[0, 128])
+        end
+      end
+      if (u = normalized.usage)
+        UsageRecord.create!(execution: execution, provider_key: execution.provider_key, metering_kind: u.metering_kind || "unknown",
+                            input_tokens: u.input_tokens, output_tokens: u.output_tokens,
+                            reported_cost: u.reported_cost, currency: u.currency, source: "provider_reported")
+      end
+      text = payload["text"].to_s
+      _, redactions = Redactor.redact_with_count(text)
+      EventStore.append!(type: normalized.type, aggregate: execution, ticket: execution.ticket, execution: execution,
+                         session: execution.agent_session, source: "provider.#{execution.provider_key}",
+                         provenance: normalized.provenance || "provider_reported", payload: payload, topics: [])
+      if redactions.positive?
+        EventStore.append!(type: "security.secret_redacted", aggregate: execution, ticket: execution.ticket, execution: execution,
+                           payload: { where: "provider_output", redactions: redactions })
+      end
+    end
+  end
+end

data/app/services/agentboard/hook_ingestion.rb

@@ -0,0 +1,100 @@
+module Agentboard
+  # Receives provider hook payloads (spec §7): validate, redact, normalize, deduplicate,
+  # associate with sessions, and queue. Payloads are bounded; only documented fields are kept.
+  module HookIngestion
+    MAX_PAYLOAD_BYTES = 256 * 1024
+
+    module_function
+
+    def ingest!(provider_key:, event_name:, raw:, project: Project.current, received_at: Time.current)
+      raise Error.validation_failed("payload too large") if raw.to_s.bytesize > MAX_PAYLOAD_BYTES
+      raise Error.validation_failed("invalid event name") unless event_name.to_s.match?(/\A[A-Za-z_.\-]{1,64}\z/)
+
+      payload = raw.to_s.strip.empty? ? {} : JSON.parse(raw)
+      raise Error.validation_failed("hook payload must be a JSON object") unless payload.is_a?(Hash)
+
+      provider = Providers.registry.fetch(provider_key)
+      events = provider.parse_hook(event_name: event_name, payload: payload)
+      raw_digest = Digest::SHA256.hexdigest(raw.to_s)
+
+      events.map.with_index do |ev, i|
+        session = resolve_session(project, provider_key, ev.external_session_id, payload)
+        dedupe = "hook:#{provider_key}:#{raw_digest}:#{i}"
+        ticket = session&.active_ticket
+        event = EventStore.append!(type: ev.type, aggregate: session || [ "project", project.id ], project: project, ticket: ticket,
+                                   session: session, source: "hook.#{provider_key}", provenance: "provider_reported",
+                                   payload: ev.payload.merge("hook_event" => event_name), dedupe_key: dedupe)
+        if session && session.metadata["agent_pid"].nil?
+          SessionCorrelation.record_agent!(session, ProcessAncestry.find_agent)
+        end
+        maybe_associate_from_branch(session, project, payload) if session && ev.type == "agent.session.started" && session.reload.active_link.nil?
+        if session && ev.type == "agent.session.ended"
+          session.update!(state: "ended", ended_at: Time.current)
+        end
+        event
+      end
+    rescue JSON::ParserError
+      raise Error.validation_failed("hook payload is not valid JSON")
+    end
+
+    # A hook-reported session id is corroborated by the provider runtime (trust "hook").
+    def resolve_session(project, provider_key, external_id, payload)
+      return nil if external_id.blank?
+
+      external_id = external_id.to_s[0, 128]
+      session = AgentSession.find_or_create_by!(project: project, provider_key: provider_key, external_session_id: external_id) do |s|
+        s.trust_level = "hook"
+        s.state = "active"
+        s.cwd = payload["cwd"].to_s[0, 500].presence
+        s.label = "#{Providers.registry.adapter_class(provider_key).display_name} #{external_id[0, 8]}"
+      end
+      fresh = session.state == "active" && session.last_seen_at && session.last_seen_at > 1.minute.ago
+      session.update_columns(last_seen_at: Time.current, state: "active") unless fresh
+      session
+    rescue ActiveRecord::RecordNotUnique
+      AgentSession.find_by!(project: project, provider_key: provider_key, external_session_id: external_id)
+    end
+
+    # Branch-name heuristic (precedence 4): recorded as needs_confirmation, never overrides explicit links.
+    def maybe_associate_from_branch(session, project, payload)
+      return if session.active_link
+
+      cwd = payload["cwd"].presence || project.root_path
+      branch = Git::Repository.new(cwd).current_branch(chdir: cwd)
+      ticket = SessionAssociation.ticket_from_branch(branch, project: project)
+      return unless ticket
+
+      SessionAssociation.link!(session: session, ticket: ticket, source: "branch_heuristic", confidence: "needs_confirmation",
+                               actor: Authorization.system_actor)
+    rescue StandardError
+      nil
+    end
+
+    # Local spooling when the database is unavailable: payloads are appended (redacted) to a
+    # user-private spool file and replayed by `agentboard hook replay` / the daemon.
+    def spool!(root:, provider_key:, event_name:, raw:)
+      dir = File.join(root.to_s, ".agentboard", "spool")
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      line = { provider: provider_key, event: event_name, raw: Redactor.redact(raw.to_s[0, MAX_PAYLOAD_BYTES]), at: Time.now.utc.iso8601 }.to_json
+      File.open(File.join(dir, "hooks.jsonl"), "a", 0o600) { |f| f.flock(File::LOCK_EX); f.puts(line) }
+    end
+
+    def replay_spool!(root:)
+      path = File.join(root.to_s, ".agentboard", "spool", "hooks.jsonl")
+      return 0 unless File.exist?(path)
+
+      processing = "#{path}.#{Process.pid}.processing"
+      File.rename(path, processing)
+      count = 0
+      File.foreach(processing) do |line|
+        entry = JSON.parse(line)
+        ingest!(provider_key: entry["provider"], event_name: entry["event"], raw: entry["raw"])
+        count += 1
+      rescue StandardError => e
+        Agentboard.logger.warn("[agentboard] spool replay skipped entry: #{e.class}")
+      end
+      File.delete(processing)
+      count
+    end
+  end
+end

data/app/services/agentboard/idempotency.rb

@@ -0,0 +1,28 @@
+module Agentboard
+  # Stores the response of a mutating request keyed by (scope, key). A replay with the same
+  # request digest returns the stored response; a different payload under the same key is
+  # rejected (VALIDATION_FAILED) to prevent accidental key reuse.
+  module Idempotency
+    TTL = 24.hours
+
+    module_function
+
+    def call(scope:, key:, request:)
+      return yield if key.blank?
+
+      digest = Ids.canonical_digest(request)
+      if (existing = IdempotencyKey.where(scope: scope, key: key).where("expires_at > ?", Time.current).first)
+        raise Error.validation_failed("Idempotency key reused with a different request") if existing.request_digest != digest
+
+        return existing.response
+      end
+
+      response = yield
+      IdempotencyKey.where(scope: scope, key: key).where("expires_at <= ?", Time.current).delete_all
+      IdempotencyKey.create!(scope: scope, key: key, request_digest: digest, response: response, expires_at: Time.current + TTL)
+      response
+    rescue ActiveRecord::RecordNotUnique
+      IdempotencyKey.find_by!(scope: scope, key: key).response
+    end
+  end
+end