agentboard 0.2.0

data/app/services/agentboard/pull_requests.rb

@@ -0,0 +1,65 @@
+module Agentboard
+  # Pull request evidence shared by the core (manual links) and Pro (GitHub webhooks).
+  module PullRequests
+    module_function
+
+    def upsert!(ticket, pr:, state:, head_ref:, head_sha:, match:, merge_verified:, source:)
+      url = pr["html_url"].to_s
+      artifact = ticket.artifacts.where(kind: "pull_request").find { |a| a.uri == url } ||
+                 ticket.artifacts.new(kind: "pull_request", uri: url)
+      artifact.assign_attributes(
+        title: "PR ##{pr["number"]}: #{pr["title"].to_s[0, 200]}", commit_sha: head_sha.presence,
+        provenance: match == "branch_name" ? "inferred" : "git_observed",
+        metadata: artifact.metadata.to_h.merge(
+          "number" => pr["number"], "state" => state, "head_ref" => head_ref, "head_sha" => head_sha,
+          "base_ref" => pr.dig("base", "ref"), "merge_commit_sha" => pr["merge_commit_sha"], "merged_at" => pr["merged_at"],
+          "merge_verified" => merge_verified, "match" => match, "source" => source
+        )
+      )
+      artifact.save!
+      EventStore.append!(type: "git.pull_request_#{state}", aggregate: ticket, ticket: ticket, source: "#{source}.github",
+                         provenance: artifact.provenance,
+                         payload: { number: pr["number"], url: url, head_sha: head_sha, match: match, merge_commit_sha: pr["merge_commit_sha"] })
+      artifact
+    end
+
+    def attempt_completion!(ticket)
+      return unless ticket.reload.status == "review"
+
+      report = CompletionPolicy.evaluate(ticket)
+      if report[:ok]
+        Tickets.transition!(ticket: ticket, to: "done", actor: Authorization.system_actor)
+      else
+        EventStore.append!(type: "ticket.completion_blocked", aggregate: ticket, ticket: ticket, source: "pull_request",
+                           payload: { missing: report[:missing] })
+      end
+    end
+
+    # Manual PR link (core feature, works without GitHub). A merge counts as verified only if
+    # the merge commit exists locally and contains the ticket's reviewed head.
+    def link_manually!(ticket:, actor:, url:, state:, merge_commit_sha: nil)
+      Authorization.authorize!(actor, "ticket.write")
+      raise Error.validation_failed("PR URL must be http(s)") unless url.to_s.match?(%r{\Ahttps?://\S+\z})
+      raise Error.validation_failed("State must be open, closed or merged") unless %w[open closed merged].include?(state)
+
+      head = Evidence.head_sha(ticket)
+      verified = false
+      if state == "merged"
+        raise Error.forbidden("Only maintainers can record a merge") unless Authorization.allowed?(actor, "ticket.complete")
+
+        repo = ticket.project.repository
+        full = repo.resolve_commit(merge_commit_sha.to_s)
+        raise Error.validation_failed("Merge commit #{merge_commit_sha} is not in the local repository (git fetch first)") unless full
+        raise Error.policy_denied("Merge commit does not contain the reviewed head #{head.to_s[0, 10]}") unless head && repo.ancestor?(head, full)
+
+        merge_commit_sha = full
+        verified = true
+      end
+      pr = { "html_url" => url, "number" => url[%r{/pull/(\d+)}, 1]&.to_i, "title" => "external", "merge_commit_sha" => merge_commit_sha }
+      artifact = upsert!(ticket, pr: pr, state: state, head_ref: nil, head_sha: head.to_s, match: "manual", merge_verified: verified, source: "manual")
+      artifact.update!(provenance: "confirmed")
+      attempt_completion!(ticket) if verified
+      artifact
+    end
+  end
+end

data/app/services/agentboard/runtime/execution_runner.rb

@@ -0,0 +1,352 @@
+module Agentboard
+  module Runtime
+    # Drives one execution attempt through the pipeline of spec §8:
+    #   validate → worktree → context → launch → stream → snapshot → verify → review handoff.
+    # Runs inside the daemon process (never inside a web worker).
+    class ExecutionRunner
+      CANCEL_POLL_SECONDS = 0.5
+      HEARTBEAT_SECONDS = 5
+
+      attr_reader :execution
+
+      def initialize(execution, config: Agentboard.config)
+        @execution = execution
+        @config = config
+        @last_cancel_poll = 0
+        @last_heartbeat = 0
+        @cancelled = false
+      end
+
+      def call
+        prepare!
+        return finish_cancelled! if cancel_requested?
+
+        outcome = launch_and_stream!
+        return finish_cancelled! if outcome == :cancelled
+        return fail!("execution_timeout", "Execution exceeded #{timeout}s") if outcome == :timeout
+
+        head = snapshot!
+        provider_ok = outcome == :succeeded
+        unless provider_ok
+          return fail!("provider_failed", "Provider exited with code #{execution.exit_code.inspect}")
+        end
+
+        verify!(head)
+      rescue Agentboard::Error => e
+        fail!(e.code.downcase, e.message)
+      rescue StandardError => e
+        Agentboard.logger.error("[agentboard] execution #{execution.id} crashed: #{e.class}: #{Redactor.redact(e.message)}")
+        Agentboard.logger.error(e.backtrace.first(8).join("\n")) if e.backtrace
+        fail!("internal_error", "#{e.class}: #{Redactor.redact(e.message)[0, 300]}")
+      ensure
+        @log&.close
+      end
+
+      private
+
+      def ticket = execution.ticket
+      def project = ticket.project
+      def provider = @provider ||= Providers.registry.fetch(execution.provider_key)
+      # The tighter of the runtime limit and a per-step workflow limit.
+      def timeout = [ (@config.runtime["execution_timeout_seconds"] || 3600).to_i, execution.metadata["timeout_seconds"]&.to_i ].compact.min
+
+      def prepare!
+        Executions.transition!(execution, "preparing")
+        repo = project.repository
+        manager = Git::WorktreeManager.new(repository: repo, workspace: @config.workspace_path)
+        resumed = resume_source
+        worktree = if resumed
+          # Resume continues in the previous attempt's worktree (it is terminal, so not shared).
+          Git::WorktreeManager::Worktree.new(path: resumed.worktree_path, branch: resumed.branch, base_sha: resumed.base_sha)
+        elsif execution.worktree_path.present? && File.directory?(execution.worktree_path)
+          Git::WorktreeManager::Worktree.new(path: execution.worktree_path, branch: execution.branch, base_sha: execution.base_sha)
+        else
+          manager.create!(ticket_key: ticket.key, attempt: execution.attempt, base_ref: base_ref)
+        end
+        @manager = manager
+        log_dir = @config.root_path.join(".agentboard", "logs", execution.id)
+        FileUtils.mkdir_p(log_dir, mode: 0o700)
+        context_dir = @config.root_path.join(".agentboard", "cache", "contexts")
+        FileUtils.mkdir_p(context_dir, mode: 0o700)
+
+        package = ContextBuilder.call(ticket: ticket, repository: repo, chdir: worktree.path, action: execution.action,
+                                      handoff: execution.metadata["handoff"],
+                                      max_tokens: (execution.agent_profile&.config || {}).fetch("context_tokens", 12_000))
+        record_snapshot(repo, worktree)
+        context_path = context_dir.join("#{execution.id}.md")
+        File.write(context_path, package.text)
+        Artifact.create!(ticket: ticket, execution: execution, kind: "context", uri: "file:#{context_path}", sha256: package.digest,
+                         title: "Context package (#{package.tokens_estimate} tokens#{package.truncated ? ", truncated" : ""})",
+                         provenance: "confirmed", metadata: package.to_h.transform_keys(&:to_s))
+        execution.update_columns(worktree_path: worktree.path, branch: worktree.branch, base_sha: worktree.base_sha,
+                          context_path: context_path.to_s, context_digest: package.digest, log_path: log_dir.join("agent.log").to_s)
+        EventStore.append!(type: "git.worktree_created", aggregate: execution, ticket: ticket, execution: execution,
+                           payload: { path: worktree.path, branch: worktree.branch, base_sha: worktree.base_sha })
+
+        session = execution.agent_session
+        SessionAssociation.link!(session: session, ticket: ticket, source: "runtime", actor: Authorization.system_actor) if session
+        if ticket.reload.status == "claimed"
+          Tickets.transition!(ticket: ticket, to: "in_progress", actor: Authorization.system_actor)
+        end
+        @prompt = build_prompt(package)
+      end
+
+      def base_ref
+        execution.metadata["base_ref"].presence || "HEAD"
+      end
+
+      def record_snapshot(repo, worktree)
+        return if RepositorySnapshot.exists?(project_id: project.id, commit_sha: worktree.base_sha)
+
+        builder = ContextBuilder.new(ticket: ticket, repository: repo, max_tokens: 1_000, chdir: worktree.path, action: "snapshot", handoff: nil)
+        RepositorySnapshot.create!(project: project, commit_sha: worktree.base_sha, metadata: builder.snapshot_metadata)
+      rescue ActiveRecord::RecordNotUnique
+        nil
+      end
+
+      def resume_source
+        id = execution.metadata["resume_of"]
+        return nil unless id
+
+        prev = Execution.find(id)
+        raise Error.invalid_transition("Cannot resume: previous attempt is still active") unless prev.terminal?
+        raise Error.workspace_conflict("Cannot resume: worktree of the previous attempt is gone") unless prev.worktree_path && File.directory?(prev.worktree_path)
+        if Execution.active.where(worktree_path: prev.worktree_path).where.not(id: execution.id).exists?
+          raise Error.workspace_conflict("Worktree is in use by another execution")
+        end
+
+        prev
+      end
+
+      def build_prompt(package)
+        action_text = {
+          "plan" => "Produce an implementation plan for the ticket. Do not modify files.",
+          "implement" => "Implement the ticket in this working directory and commit your changes with a descriptive message.",
+          "review" => "Review the changes between the base commit and HEAD for correctness, security and test coverage. Report findings; do not modify files.",
+          "fix_tests" => "Make the failing verification commands pass. Commit your changes.",
+          "summarize" => "Summarize the current state of the work for a human reviewer."
+        }.fetch(execution.action, "Work on the ticket.")
+        <<~PROMPT
+          You are working on ticket #{ticket.key} managed by AgentBoard.
+          #{action_text}
+          AgentBoard runs verification independently; your own claims of success are not evidence.
+
+          #{package.text}
+        PROMPT
+      end
+
+      def launch_and_stream!
+        spec = if execution.metadata["resume_of"]
+          provider.resume_spec(execution: execution, worktree: execution.worktree_path,
+                               input: execution.metadata["resume_message"].presence || "Continue the task.")
+        else
+          provider.launch_spec(execution: execution, worktree: execution.worktree_path, context_path: execution.context_path, prompt: @prompt)
+        end
+        @log = File.open(execution.log_path, "ab", 0o600)
+        max_bytes = @config.runtime["max_log_bytes"].to_i
+        argv = spec.argv
+        cli_env = {}
+        if execution.metadata["isolation"] == "container"
+          cli_env = AgentContainer.cli_env(spec)
+          AgentContainer.ensure_network!
+          @container = "agentboard-exec-#{execution.id.delete("-")[-16..]}"
+          argv = AgentContainer.wrap(spec, execution: execution, name: @container)
+          execution.update_columns(metadata: execution.metadata.merge("container" => @container, "image" => AgentContainer.image))
+          EventStore.append!(type: "agent.execution.container_started", aggregate: execution, ticket: ticket, execution: execution,
+                             payload: { container: @container, image: AgentContainer.image, network: AgentContainer.network_name,
+                                        egress: AgentContainer.egress_allowlist })
+        end
+        handle = Subprocess.spawn(argv, chdir: spec.chdir, env: spec.env.to_h.merge(cli_env).merge("AGENTBOARD_EXECUTION_ID" => execution.id),
+                                  passthrough_env: (spec.passthrough_env || []) + %w[DOCKER_HOST DOCKER_CONTEXT DOCKER_CONFIG DOCKER_CERT_PATH DOCKER_TLS_VERIFY],
+                                  stdin_data: spec.stdin_data)
+        execution.update_columns(pid: handle[:pid], pgid: handle[:pgid], process_fingerprint: Subprocess.fingerprint(handle[:pid]), heartbeat_at: Time.current)
+        Executions.transition!(execution, "running")
+
+        started = Subprocess.monotonic
+        terminal_status = nil
+        buffer = +""
+        reader = handle[:reader]
+        result = nil
+        loop do
+          if Subprocess.monotonic - started > timeout
+            Subprocess.terminate(handle[:pgid], grace: grace)
+            AgentContainer.remove(@container)
+            result = :timeout
+            break
+          end
+          if cancel_requested?
+            Subprocess.terminate(handle[:pgid], grace: grace)
+            AgentContainer.remove(@container) # killing the docker CLI does not stop the container
+            result = :cancelled
+            break
+          end
+          heartbeat!
+          next unless IO.select([ reader ], nil, nil, 0.2)
+
+          chunk = begin
+            reader.read_nonblock(65_536)
+          rescue IO::WaitReadable
+            next
+          rescue EOFError
+            break
+          end
+          buffer << chunk.force_encoding("UTF-8").scrub
+          while (idx = buffer.index("\n"))
+            line = buffer.slice!(0..idx)
+            status = handle_line(line, max_bytes)
+            terminal_status = status if status
+          end
+        end
+        handle_line(buffer, max_bytes) if buffer.present? && result.nil?
+        @last_heartbeat = 0
+        heartbeat! # final resource sample
+        reader.close unless reader.closed?
+        _, status = ::Process.wait2(handle[:pid])
+        execution.update_columns(exit_code: status.exitstatus)
+        return result if result
+
+        terminal_status == "failed" || !status.success? ? :failed : :succeeded
+      end
+
+      def handle_line(line, max_bytes)
+        redacted, count = Redactor.redact_with_count(line)
+        if execution.log_bytes < max_bytes
+          @log.write(redacted)
+          @log.flush
+          execution.log_bytes += redacted.bytesize
+        elsif !execution.log_truncated
+          @log.write("\n[agentboard: log truncated at #{max_bytes} bytes]\n")
+          execution.log_truncated = true
+        end
+        if count.positive?
+          EventStore.append!(type: "security.secret_redacted", aggregate: execution, ticket: ticket, execution: execution,
+                             payload: { where: "provider_output", redactions: count })
+        end
+        status = nil
+        provider.parse_event(raw_event: redacted).each do |ev|
+          Executions.record_provider_event!(execution, ev)
+          status = ev.status if ev.terminal
+          if ev.status == "waiting_for_permission"
+            # Print-mode providers do not block on permission; the request is recorded and
+            # surfaced. Interactive permission bridging requires a provider protocol.
+            execution.update_columns(metadata: execution.metadata.merge("permission_requests" => execution.metadata["permission_requests"].to_i + 1))
+          end
+        end
+        status
+      ensure
+        execution.update_columns(log_bytes: execution.log_bytes, log_truncated: execution.log_truncated)
+      end
+
+      def heartbeat!
+        now = Subprocess.monotonic
+        return if now - @last_heartbeat < HEARTBEAT_SECONDS
+
+        @last_heartbeat = now
+        attrs = { heartbeat_at: Time.current }
+        if execution.pgid && (usage = Subprocess.group_usage(execution.pgid))
+          @peak_rss = [ @peak_rss.to_i, usage[:rss_kb] ].max
+          @cpu = [ @cpu.to_f, usage[:cpu_seconds] ].max
+          attrs[:metadata] = execution.metadata.merge("resources" => { "peak_rss_kb" => @peak_rss, "cpu_seconds" => @cpu.round(2),
+                                                                       "processes" => usage[:processes] })
+          execution.metadata = attrs[:metadata]
+        end
+        execution.update_columns(attrs)
+      end
+
+      def cancel_requested?
+        return true if @cancelled
+
+        now = Subprocess.monotonic
+        return false if now - @last_cancel_poll < CANCEL_POLL_SECONDS
+
+        @last_cancel_poll = now
+        @cancelled = Execution.where(id: execution.id).where.not(cancel_requested_at: nil).exists?
+      end
+
+      def grace = @config.runtime["cancel_grace_seconds"].to_i
+
+      # Bind whatever the agent produced to an immutable commit (evidence), even on failure.
+      def snapshot!
+        return nil unless execution.worktree_path && File.directory?(execution.worktree_path)
+
+        head = @manager.snapshot!(execution.worktree_path, message: "#{ticket.key}: AgentBoard snapshot (#{execution.provider_key} exec-#{execution.attempt})")
+        changes = @manager.changes(execution.worktree_path, execution.base_sha)
+        execution.update_columns(head_sha: head)
+        if changes[:files].any?
+          Artifact.create!(ticket: ticket, execution: execution, kind: "commit", uri: "git:#{head}", commit_sha: head,
+                           title: "#{changes[:stat][:files]} files (+#{changes[:stat][:insertions]}/−#{changes[:stat][:deletions]})",
+                           provenance: "git_observed",
+                           metadata: { "verified_in_repo" => true, "branch" => execution.branch, "files" => changes[:files].first(200), "stat" => changes[:stat] })
+          Approvals.invalidate_stale!(ticket: ticket, head_sha: head)
+        end
+        EventStore.append!(type: "git.snapshot", aggregate: execution, ticket: ticket, execution: execution, provenance: "git_observed",
+                           payload: { head_sha: head, base_sha: execution.base_sha, files: changes[:files].first(50), stat: changes[:stat] })
+        @changed = changes[:files].any?
+        head
+      end
+
+      def verify!(head)
+        if %w[plan review summarize].include?(execution.action) || !@changed
+          Executions.transition!(execution, "verifying")
+          Executions.transition!(execution, "completed", summary: last_summary)
+          return execution
+        end
+
+        Executions.transition!(execution, "verifying")
+        if ticket.reload.status == "in_progress"
+          Tickets.transition!(ticket: ticket, to: "testing", actor: Authorization.system_actor)
+        end
+        results = VerificationService.run_catalog!(execution: execution, chdir: execution.worktree_path, cancel_check: -> { cancel_requested? })
+        return finish_cancelled! if cancel_requested?
+
+        required_ok = results.select(&:required).all?(&:passed?)
+        if required_ok
+          Executions.transition!(execution, "completed", summary: last_summary)
+          if ticket.reload.status == "testing"
+            Tickets.transition!(ticket: ticket, to: "review", actor: Authorization.system_actor, head_sha: head)
+            Approvals.request_review!(ticket: ticket, actor: Authorization.system_actor, head_sha: head, summary: last_summary)
+          end
+        else
+          failed = results.reject(&:passed?).map(&:name)
+          Executions.transition!(execution, "failed", failure_code: "verification_failed", failure_message: "Checks failed: #{failed.join(", ")}",
+                                                      summary: last_summary)
+          Tickets.transition!(ticket: ticket, to: "in_progress", actor: Authorization.system_actor) if ticket.reload.status == "testing"
+        end
+        release_lease!
+        execution
+      end
+
+      def last_summary
+        Event.where(execution_id: execution.id, event_type: %w[agent.execution.result agent.execution.message])
+             .order(received_at: :desc).limit(1).pick(:payload)&.then { |p| p["summary"].presence || p["text"] }.to_s[0, 4000]
+      end
+
+      def release_lease!
+        session = execution.agent_session
+        ticket.leases.live.where(agent_session_id: session&.id).update_all(released_at: Time.current, release_reason: "execution_finished", updated_at: Time.current)
+      end
+
+      def finish_cancelled!
+        execution.reload
+        return execution if execution.terminal?
+
+        Executions.transition!(execution, "cancelled", cancel_reason: execution.cancel_reason || "cancelled")
+        release_lease!
+        execution
+      end
+
+      def fail!(code, message)
+        execution.reload
+        return execution if execution.terminal?
+
+        to = execution.status == "queued" ? "failed" : "failed"
+        Executions.transition!(execution, to, failure_code: code.to_s[0, 64], failure_message: message.to_s[0, 2000])
+        release_lease!
+        execution
+      rescue StandardError => e
+        Agentboard.logger.error("[agentboard] could not mark #{execution.id} failed: #{e.class}")
+        execution
+      end
+    end
+  end
+end

data/app/services/agentboard/runtime/ipc_handler.rb

@@ -0,0 +1,55 @@
+module Agentboard
+  module Runtime
+    # Maps IPC operations (spec §27.2) to domain services. Runs inside the daemon; every
+    # request has already been authenticated by IPC::Server.
+    class IpcHandler
+      def initialize(supervisor)
+        @supervisor = supervisor
+      end
+
+      def call(op, params)
+        ActiveRecord::Base.connection_pool.with_connection { dispatch(op, params) }
+      end
+
+      private
+
+      def actor = Authorization.local_human
+
+      def dispatch(op, params)
+        case op
+        when "runtime.health" then @supervisor.health
+        when "runtime.reconcile" then Reconciler.new.call
+        when "execution.enqueue"
+          ticket = find_ticket(params)
+          execution = Executions.enqueue!(ticket: ticket, provider_key: params.fetch("provider", "fake"), actor: actor,
+                                          action: params.fetch("action", "implement"), idempotency_key: params["idempotency_key"],
+                                          metadata: params.slice("scenario"))
+          { execution_id: execution.id, status: execution.status, attempt: execution.attempt }
+        when "execution.status"
+          e = Execution.find(params.fetch("execution_id"))
+          { execution_id: e.id, state: e.status, attempt: e.attempt, started_at: e.started_at, finished_at: e.finished_at,
+            exit_code: e.exit_code, failure_code: e.failure_code, head_sha: e.head_sha }
+        when "execution.cancel"
+          e = Execution.find(params.fetch("execution_id"))
+          Idempotency.call(scope: "execution.cancel", key: params["idempotency_key"], request: params.slice("execution_id", "reason")) do
+            e = Executions.request_cancel!(execution: e, actor: actor, reason: params["reason"] || "cancelled via runtime")
+            { "accepted" => true, "current_state" => e.status }
+          end
+        when "execution.input"
+          raise Error.capability_unavailable("Interactive input bridging is not supported by the configured providers in print mode")
+        when "execution.events"
+          e = Execution.find(params.fetch("execution_id"))
+          cursor = params["cursor"].to_i
+          events = Event.where(aggregate_type: "execution", aggregate_id: e.id).where("sequence > ?", cursor).order(:sequence).limit(500)
+          { events: events.map(&:envelope), next_cursor: events.last&.sequence || cursor, terminal: e.reload.terminal? }
+        else
+          raise Error.not_found("Unknown runtime operation #{op}")
+        end
+      end
+
+      def find_ticket(params)
+        Ticket.find_by_key!(params.fetch("ticket_key"))
+      end
+    end
+  end
+end

data/app/services/agentboard/runtime/reconciler.rb

@@ -0,0 +1,42 @@
+module Agentboard
+  module Runtime
+    # Restart reconciliation (spec §27.4, AT-07). For every non-terminal execution owned by
+    # a previous daemon: the stdout pipe is gone, so the attempt cannot be safely reattached.
+    # Live orphan processes are terminated; the attempt is marked `interrupted` with worktree
+    # and logs preserved. Uncertain operations are never re-run automatically.
+    class Reconciler
+      def initialize(logger: Agentboard.logger)
+        @logger = logger
+      end
+
+      def call
+        report = { recovered: [], interrupted: [], orphaned: [] }
+        Execution.where(status: StateMachines::Execution::ACTIVE - [ "queued" ]).find_each do |execution|
+          AgentContainer.remove(execution.metadata["container"]) if execution.metadata["container"]
+          if execution.pid && Subprocess.alive?(execution.pid) && fingerprint_matches?(execution)
+            Subprocess.terminate(execution.pgid || execution.pid, grace: Agentboard.config.runtime["cancel_grace_seconds"].to_i)
+            report[:orphaned] << execution.id
+          end
+          Executions.transition!(execution, "interrupted", failure_code: "runtime_restart",
+                                                           failure_message: "Runtime restarted while the attempt was #{execution.status}; retry explicitly.")
+          execution.ticket.leases.live.where(agent_session_id: execution.agent_session_id)
+                   .update_all(released_at: Time.current, release_reason: "execution_interrupted", updated_at: Time.current)
+          report[:interrupted] << execution.id
+        rescue StandardError => e
+          @logger.error("[agentboard] reconcile #{execution.id} failed: #{e.class}")
+        end
+        if report.values.any?(&:any?)
+          EventStore.append!(type: "agent.runtime.reconciled", aggregate: [ "runtime", "local" ], payload: report)
+        end
+        report
+      end
+
+      private
+
+      # PIDs are reused by the OS; only signal a process whose identity still matches.
+      def fingerprint_matches?(execution)
+        execution.process_fingerprint.present? && Subprocess.fingerprint(execution.pid) == execution.process_fingerprint
+      end
+    end
+  end
+end

data/app/services/agentboard/runtime/supervisor.rb

@@ -0,0 +1,96 @@
+module Agentboard
+  module Runtime
+    # Daemon main loop (spec §27.3). Claims queued executions up to the concurrency limit,
+    # runs each in a bounded worker thread, drains the outbox, advances workflows and expires
+    # approvals. Never blocks the loop on a single process.
+    class Supervisor
+      attr_reader :started_at, :workers
+
+      def initialize(config: Agentboard.config, logger: Agentboard.logger)
+        @config = config
+        @logger = logger
+        @workers = {}
+        @mutex = Mutex.new
+        @stopping = false
+        @started_at = Time.current
+      end
+
+      def run(once: false)
+        Reconciler.new(logger: @logger).call
+        loop do
+          tick
+          break if once || @stopping
+
+          sleep @config.runtime["poll_interval"].to_f.clamp(0.05, 10)
+        end
+        shutdown
+      end
+
+      def stop! = (@stopping = true)
+      def active_count = @mutex.synchronize { @workers.count { |_, t| t.alive? } }
+
+      def tick
+        reap
+        start_queued
+        WorkflowEngine.tick
+        Outbox.drain(limit: 200)
+        Approvals.expire_due!
+        Extensions.run(:runtime_tick)
+      rescue StandardError => e
+        @logger.error("[agentboard] supervisor tick failed: #{e.class}: #{Redactor.redact(e.message)}")
+      end
+
+      # Fair queue: explicit priority, then age; one active execution per ticket.
+      def start_queued
+        capacity = @config.max_concurrent_executions - active_count
+        return if capacity <= 0
+
+        candidates = Execution.where(status: "queued").joins(:ticket)
+                              .order("agentboard_tickets.priority ASC, agentboard_executions.created_at ASC").limit(capacity * 4)
+        candidates.each do |execution|
+          break if capacity <= 0
+          next if @workers.key?(execution.id)
+          next if Execution.active.where(ticket_id: execution.ticket_id).where.not(id: execution.id).where.not(status: "queued").exists?
+
+          claimed = Execution.where(id: execution.id, status: "queued").update_all(updated_at: Time.current, heartbeat_at: Time.current)
+          next if claimed.zero?
+
+          capacity -= 1
+          spawn_worker(execution.id)
+        end
+      end
+
+      def spawn_worker(execution_id)
+        thread = Thread.new do
+          Thread.current.name = "agentboard-exec-#{execution_id[0, 8]}"
+          ActiveRecord::Base.connection_pool.with_connection do
+            ExecutionRunner.new(Execution.find(execution_id), config: @config).call
+          end
+        rescue StandardError => e
+          @logger.error("[agentboard] worker #{execution_id} failed: #{e.class}")
+        end
+        @mutex.synchronize { @workers[execution_id] = thread }
+      end
+
+      def reap
+        @mutex.synchronize { @workers.delete_if { |_, t| !t.alive? } }
+      end
+
+      # Graceful shutdown: request cancellation of running work and wait briefly. Anything
+      # still running is reconciled as interrupted on the next start.
+      def shutdown
+        ids = @mutex.synchronize { @workers.keys }
+        return if ids.empty?
+
+        Execution.where(id: ids).active.update_all(cancel_requested_at: Time.current, cancel_reason: "daemon shutdown")
+        deadline = Subprocess.monotonic + @config.runtime["cancel_grace_seconds"].to_i + 5
+        sleep 0.1 while Subprocess.monotonic < deadline && active_count.positive?
+      end
+
+      def health
+        { version: Agentboard::VERSION, pid: ::Process.pid, uptime: (Time.current - @started_at).round, active: active_count,
+          queued: Execution.where(status: "queued").count, max_concurrent: @config.max_concurrent_executions }
+      end
+    end
+  end
+end

data/app/services/agentboard/session_association.rb

@@ -0,0 +1,44 @@
+module Agentboard
+  # Associates an agent session with (at most) one active ticket (spec §7).
+  # Precedence: MCP selection > CLI attach > dashboard > branch heuristic > provider metadata.
+  # An automatic association never replaces an explicit human choice.
+  module SessionAssociation
+    module_function
+
+    def link!(session:, ticket:, source:, actor:, confidence: "confirmed")
+      raise Error.validation_failed("Unknown association source") unless SessionTicketLink::SOURCES.key?(source)
+
+      SessionTicketLink.transaction do
+        current = session.ticket_links.active.lock.first
+        if current
+          return current if current.ticket_id == ticket.id && current.precedence <= SessionTicketLink::SOURCES[source]
+          if current.explicit? && !SessionTicketLink::EXPLICIT.include?(source)
+            raise Error.policy_denied("Session is explicitly attached to #{current.ticket.key}; automatic association ignored")
+          end
+
+          current.update!(ended_at: Time.current)
+        end
+        link = session.ticket_links.create!(ticket: ticket, source: source, confidence: confidence, started_at: Time.current)
+        EventStore.append!(type: "agent.session.attached", aggregate: session, project: session.project, ticket: ticket, session: session,
+                           actor: actor, provenance: (source == "branch_heuristic" ? "inferred" : "confirmed"),
+                           payload: { ticket_key: ticket.key, source: source, confidence: confidence, previous_ticket_id: current&.ticket_id })
+        link
+      end
+    end
+
+    def unlink!(session:, actor:)
+      link = session.ticket_links.active.first
+      return unless link
+
+      link.update!(ended_at: Time.current)
+      EventStore.append!(type: "agent.session.detached", aggregate: session, project: session.project, ticket: link.ticket,
+                         session: session, actor: actor, payload: { ticket_key: link.ticket.key })
+    end
+
+    # Branch heuristic: `agentboard/AB-142/...`, `feature/AB-142-foo`, etc. Requires confirmation.
+    def ticket_from_branch(branch, project:)
+      match = branch.to_s.match(/(?:\A|[\/_-])(#{Regexp.escape(project.key)}-\d+)(?:\z|[\/_-])/i)
+      match && Ticket.find_by_key(match[1].upcase, project: project)
+    end
+  end
+end