agentboard 0.2.0

data/app/services/agentboard/session_correlation.rb

@@ -0,0 +1,56 @@
+module Agentboard
+  # Links sessions that belong to the same agent process (see ProcessAncestry). A hook
+  # session corroborates an MCP session and vice versa; links propagate ticket context.
+  module SessionCorrelation
+    module_function
+
+    def record_agent!(session, agent)
+      return unless agent
+
+      session.update_columns(metadata: session.metadata.merge(agent.to_h))
+      correlate!(session)
+    end
+
+    def peers(session)
+      pid = session.metadata["agent_pid"]
+      fp = session.metadata["agent_fingerprint"]
+      return AgentSession.none unless pid && fp
+
+      AgentSession.where(project_id: session.project_id, state: "active").where.not(id: session.id).select do |s|
+        s.metadata["agent_pid"] == pid && s.metadata["agent_fingerprint"] == fp
+      end
+    end
+
+    def correlate!(session)
+      peers(session).each do |peer|
+        next if peer.metadata["correlated_session_id"] == session.id
+
+        peer.update_columns(metadata: peer.metadata.merge("correlated_session_id" => session.id))
+        session.update_columns(metadata: session.metadata.merge("correlated_session_id" => peer.id))
+        EventStore.append!(type: "agent.session.correlated", aggregate: session, project: session.project, session: session,
+                           payload: { peer_session_id: peer.id, peer_trust: peer.trust_level, agent_pid: session.metadata["agent_pid"] })
+        # Propagate an explicit ticket link to the peer that has none.
+        [ [ peer, session ], [ session, peer ] ].each do |src, dst|
+          link = src.active_link
+          next unless link&.explicit? && dst.active_link.nil?
+
+          SessionAssociation.link!(session: dst, ticket: link.ticket, source: link.source == "runtime" ? "runtime" : "mcp",
+                                   actor: Authorization.system_actor)
+        end
+      end
+    end
+
+    # After an explicit MCP link, pull the correlated hook session along.
+    def propagate_link!(session)
+      peer_id = session.metadata["correlated_session_id"]
+      peer = peer_id && AgentSession.find_by(id: peer_id, state: "active")
+      link = session.active_link
+      return unless peer && link
+      return if peer.active_link&.ticket_id == link.ticket_id
+
+      SessionAssociation.link!(session: peer, ticket: link.ticket, source: "mcp", actor: Authorization.system_actor)
+    rescue Agentboard::Error
+      nil
+    end
+  end
+end

data/app/services/agentboard/session_credential.rb

@@ -0,0 +1,44 @@
+module Agentboard
+  # Short-lived local capability credential for MCP sessions (spec §25.4). The MCP process
+  # holds the secret in memory; only its digest is stored. Every tool call verifies it, the
+  # credential rotates before expiry, and a human can revoke the session at any time.
+  module SessionCredential
+    TTL = 15.minutes
+    ROTATE_BEFORE = 2.minutes
+
+    Credential = Struct.new(:token, :expires_at, keyword_init: true)
+
+    module_function
+
+    def issue!(session)
+      token = Ids.token
+      expires = Time.current + TTL
+      session.update_columns(credential_digest: Ids.digest(token),
+                             metadata: session.metadata.merge("credential_expires_at" => expires.utc.iso8601))
+      Credential.new(token: token, expires_at: expires)
+    end
+
+    # Returns the (possibly rotated) credential or raises UNAUTHORIZED.
+    def verify!(session, credential)
+      session.reload
+      raise Error.unauthorized("Session was revoked by a human") if session.state == "revoked"
+      raise Error.unauthorized("Session has ended") if session.state == "ended"
+      raise Error.unauthorized("Missing session credential") unless credential
+      raise Error.unauthorized("Invalid session credential") unless Ids.secure_match?(credential.token, session.credential_digest)
+      raise Error.unauthorized("Session credential expired") if credential.expires_at <= Time.current
+
+      credential.expires_at - Time.current < ROTATE_BEFORE ? issue!(session) : credential
+    end
+
+    def revoke!(session, actor:, reason: nil)
+      raise Error.forbidden("Only humans can revoke sessions") unless actor.human?
+      Authorization.authorize!(actor, "session.manage")
+
+      session.update_columns(state: "revoked", credential_digest: nil, ended_at: Time.current)
+      session.leases.live.update_all(released_at: Time.current, release_reason: "session_revoked", updated_at: Time.current)
+      SessionTicketLink.active.where(agent_session_id: session.id).update_all(ended_at: Time.current, updated_at: Time.current)
+      EventStore.append!(type: "security.session_revoked", aggregate: session, project: session.project, session: session, actor: actor,
+                         payload: { reason: reason })
+    end
+  end
+end

data/app/services/agentboard/ticket_advisor.rb

@@ -0,0 +1,60 @@
+module Agentboard
+  # Drafting assistance (spec §10): deterministic suggestions that a human must accept.
+  # Nothing here mutates a ticket; accepting goes through the normal Tickets services.
+  module TicketAdvisor
+    Suggestion = Struct.new(:kind, :text, :value, :reason, keyword_init: true)
+
+    CRITERIA_TEMPLATES = {
+      "bug" => [ "A regression test reproduces the bug and passes with the fix", "Root cause is described in the PR or a comment" ],
+      "feature" => [ "Automated tests cover the new behaviour", "User-facing changes are documented" ],
+      "task" => [ "The change is covered by existing or new tests" ],
+      "chore" => [ "The full test suite passes" ],
+      "spike" => [ "Findings and a recommendation are written up as a comment" ]
+    }.freeze
+
+    module_function
+
+    def suggest(ticket)
+      builder = ContextBuilder.new(ticket: ticket, repository: ticket.project.repository, max_tokens: 2_000, chdir: nil, action: "advise", handoff: nil)
+      files = builder.relevant_files(limit: 8)
+      suggestions = []
+      files.each { |path, score| suggestions << Suggestion.new(kind: "file", text: path, value: path, reason: "keyword match score #{score}") }
+      suggestions << complexity(ticket, files)
+      existing = ticket.acceptance_criteria.map { |c| c.description.downcase }
+      CRITERIA_TEMPLATES.fetch(ticket.kind, []).reject { |c| existing.include?(c.downcase) }.each do |c|
+        suggestions << Suggestion.new(kind: "criterion", text: c, value: c, reason: "common for #{ticket.kind} tickets")
+      end
+      subtasks(ticket).each { |s| suggestions << Suggestion.new(kind: "subtask", text: s, value: s, reason: "listed in the description") }
+      dependencies(ticket, builder, files).each { |t, why| suggestions << Suggestion.new(kind: "dependency", text: "#{t.key} — #{t.title}", value: t.key, reason: why) }
+      suggestions
+    end
+
+    def complexity(ticket, files)
+      score = files.size + ticket.description.to_s.scan(/\S+/).size / 80 + ticket.acceptance_criteria.size
+      size = score <= 3 ? "S" : (score <= 7 ? "M" : "L")
+      Suggestion.new(kind: "complexity", text: size, value: size, reason: "#{files.size} relevant files, #{ticket.acceptance_criteria.size} criteria")
+    end
+
+    # Bullet or numbered lines in the description become subtask candidates.
+    def subtasks(ticket)
+      existing = ticket.subtasks.pluck(:title).map(&:downcase)
+      ticket.description.to_s.lines.map(&:chomp).filter_map { |l| l[/\A\s*(?:[-*•]|\d+[.)])\s+(.{6,140})\z/, 1]&.strip }
+            .reject { |s| existing.include?(s.downcase) }.uniq.first(8)
+    end
+
+    # Open tickets touching the same files or sharing many keywords.
+    def dependencies(ticket, builder, files)
+      mine = builder.ticket_keywords.to_set
+      file_set = files.map(&:first).to_set
+      candidates = ticket.project.tickets.open.where.not(id: [ ticket.id ] + ticket.depends_on.pluck(:id) + ticket.dependents.pluck(:id)).limit(200)
+      candidates.filter_map do |other|
+        ob = ContextBuilder.new(ticket: other, repository: ticket.project.repository, max_tokens: 1_000, chdir: nil, action: "advise", handoff: nil)
+        overlap = (ob.ticket_keywords.to_set & mine).size
+        shared = (ob.relevant_files(limit: 8).map(&:first).to_set & file_set).size
+        next unless shared.positive? || overlap >= 4
+
+        [ other, shared.positive? ? "touches #{shared} of the same files" : "#{overlap} shared keywords" ]
+      end.first(3)
+    end
+  end
+end

data/app/services/agentboard/tickets.rb

@@ -0,0 +1,218 @@
+module Agentboard
+  # Ticket domain operations. Every mutation: authorizes the actor, uses optimistic
+  # locking, emits an event in the same transaction, and never trusts agent claims.
+  module Tickets
+    module_function
+
+    def create!(project:, actor:, title:, description: "", kind: "task", priority: 2, criteria: [], labels: [],
+                parent: nil, milestone: nil, status: "backlog", correlation_id: nil)
+      Authorization.authorize!(actor, "ticket.write")
+      raise Error.validation_failed("New tickets start in backlog or ready") unless %w[backlog ready].include?(status)
+
+      Ticket.transaction do
+        number = project.next_ticket_number!
+        ticket = project.tickets.create!(
+          number: number, title: title.to_s.strip, description: description.to_s, kind: kind, priority: priority.to_i,
+          labels: Array(labels).map(&:to_s).reject(&:blank?).uniq, parent: parent, milestone: milestone,
+          created_by_id: actor.id, status: "backlog", position: Time.current.to_f
+        )
+        Array(criteria).map(&:to_s).map(&:strip).reject(&:blank?).each do |text|
+          ticket.acceptance_criteria.create!(description: text)
+        end
+        EventStore.append!(type: "ticket.created", aggregate: ticket, ticket: ticket, actor: actor, correlation_id: correlation_id,
+                           payload: { key: ticket.key, title: ticket.title, kind: kind, priority: ticket.priority })
+        transition!(ticket: ticket, to: "ready", actor: actor) if status == "ready"
+        ticket
+      end
+    end
+
+    def update!(ticket:, actor:, attributes:, expected_version: nil, correlation_id: nil)
+      Authorization.authorize!(actor, "ticket.write")
+      allowed = attributes.to_h.symbolize_keys.slice(:title, :description, :kind, :priority, :labels, :milestone_id, :parent_id, :assignee_profile_id)
+      allowed[:milestone_id] = allowed[:milestone_id].presence if allowed.key?(:milestone_id)
+      if allowed[:milestone_id] && !ticket.project.milestones.exists?(allowed[:milestone_id])
+        raise Error.validation_failed("Milestone belongs to another project")
+      end
+      allowed[:labels] = Array(allowed[:labels]).flat_map { |l| l.to_s.split(",") }.map(&:strip).reject(&:blank?).uniq if allowed.key?(:labels)
+      Ticket.transaction do
+        ticket.lock_version = expected_version.to_i if expected_version
+        before = ticket.attributes.slice(*allowed.keys.map(&:to_s))
+        ticket.update!(allowed)
+        changes = ticket.saved_changes.except("updated_at", "lock_version")
+        if changes.any?
+          EventStore.append!(type: "ticket.updated", aggregate: ticket, ticket: ticket, actor: actor, correlation_id: correlation_id,
+                             payload: { changes: changes.transform_values { |(a, b)| { from: a, to: b } }, before: before.keys })
+        end
+        ticket
+      end
+    end
+
+    # Moves a ticket through the state machine (spec §24.1) enforcing guards.
+    #
+    # options:
+    #   reason:          required for blocked / cancelled / reopened / criteria override
+    #   lease_token:     required when an agent actor mutates a claimed ticket
+    #   session:         trusted AgentSession for agent actors
+    #   override_criteria: human-only, backlog -> ready without criteria
+    #   verification_requested: in_progress -> testing without an implementation artifact
+    #   head_sha:        commit under review for testing -> review
+    def transition!(ticket:, to:, actor:, reason: nil, lease_token: nil, session: nil, expected_version: nil,
+                    override_criteria: false, verification_requested: false, head_sha: nil, correlation_id: nil)
+      to = to.to_s
+      Authorization.authorize!(actor, permission_for(to))
+      if actor.agent? && Authorization::HUMAN_ONLY_TRANSITIONS.include?(to)
+        raise Error.forbidden("Agents cannot move tickets to #{to}; a human must do this")
+      end
+
+      # ready -> claimed always goes through the lease service.
+      if to == "claimed"
+        claim = LeaseService.claim!(ticket: ticket, actor: actor, session: session, expected_version: expected_version, correlation_id: correlation_id)
+        return ticket.reload.tap { |t| t.instance_variable_set(:@issued_lease, claim) }
+      end
+
+      Ticket.transaction do
+        ticket.lock!
+        if expected_version && ticket.lock_version != expected_version.to_i
+          raise Error.version_conflict("Ticket #{ticket.key} changed (version #{ticket.lock_version})", current_version: ticket.lock_version)
+        end
+        from = ticket.status
+        return ticket if from == to
+
+        StateMachines::Ticket.assert!(from, to)
+        lease = enforce_lease!(ticket, actor, lease_token, session)
+        guard!(ticket, from, to, actor: actor, reason: reason, override_criteria: override_criteria,
+               verification_requested: verification_requested, head_sha: head_sha, lease: lease)
+
+        attrs = { status: to }
+        attrs[:blocked_reason] = (to == "blocked" ? reason : nil)
+        attrs[:completed_at] = (to == "done" ? Time.current : nil)
+        ticket.update!(attrs)
+
+        if %w[ready done cancelled backlog].include?(to)
+          LeaseService.release_all!(ticket: ticket, reason: "ticket_#{to}")
+        end
+        if %w[done cancelled].include?(to)
+          SessionTicketLink.active.where(ticket_id: ticket.id).update_all(ended_at: Time.current, updated_at: Time.current)
+        end
+
+        EventStore.append!(type: "ticket.transitioned", aggregate: ticket, ticket: ticket, actor: actor, session: session,
+                           correlation_id: correlation_id,
+                           payload: { from: from, to: to, reason: reason, head_sha: head_sha, override_criteria: override_criteria.presence }.compact)
+        ticket
+      end
+    end
+
+    def permission_for(to)
+      case to
+      when "done" then "ticket.transition" # gated by CompletionPolicy
+      when "reopened" then "ticket.reopen"
+      when "cancelled" then "ticket.cancel"
+      when "claimed" then "ticket.claim"
+      else "ticket.transition"
+      end
+    end
+
+    def enforce_lease!(ticket, actor, token, session)
+      live = ticket.leases.live.where("expires_at > ?", Time.current).first
+      if actor.agent?
+        # Agents may only mutate tickets they hold a valid, current lease for.
+        return LeaseService.validate!(ticket: ticket, token: token, session: session)
+      end
+      live
+    end
+
+    def guard!(ticket, from, to, actor:, reason:, override_criteria:, verification_requested:, head_sha:, lease:)
+      case [ from, to ]
+      in [ "backlog", "ready" ]
+        if ticket.acceptance_criteria.none?
+          unless override_criteria && actor.human? && reason.present?
+            raise Error.policy_denied("Add acceptance criteria before marking #{ticket.key} ready (or override with a reason)")
+          end
+        end
+      in [ "claimed", "in_progress" ]
+        if actor.agent?
+          link = SessionTicketLink.active.find_by(ticket_id: ticket.id, agent_session_id: lease&.agent_session_id)
+          raise Error.policy_denied("Session must be bound to the ticket (start_work) before work begins") unless link
+        elsif lease.nil?
+          raise Error.policy_denied("#{ticket.key} has no active lease; claim it first")
+        end
+      in [ "in_progress", "testing" ]
+        has_impl = ticket.artifacts.where(kind: %w[commit diff pull_request]).exists? || ticket.executions.where.not(head_sha: nil).exists?
+        unless has_impl || verification_requested
+          raise Error.policy_denied("Attach an implementation artifact (commit/diff) or explicitly request verification")
+        end
+      in [ "testing", "review" ]
+        report = CompletionPolicy.checks_report(ticket, head_sha: head_sha || Evidence.head_sha(ticket))
+        raise Error.policy_denied("Required checks have not passed for the current head: #{report[:missing].join("; ")}", **report) unless report[:ok]
+      in [ "review", "done" ]
+        report = CompletionPolicy.evaluate(ticket, actor: actor)
+        raise Error.policy_denied("Completion policy not satisfied: #{report[:missing].join("; ")}", missing: report[:missing]) unless report[:ok]
+      in [ _, "blocked" ]
+        raise Error.validation_failed("A blocker reason is required") if reason.blank?
+      in [ "blocked", "ready" ]
+        raise Error.policy_denied("Dependencies are not finished: #{ticket.unsatisfied_dependencies.map(&:key).join(", ")}") unless ticket.dependencies_satisfied?
+      in [ "done", "reopened" ] | [ _, "cancelled" ]
+        raise Error.validation_failed("A reason is required") if reason.blank?
+      else
+        nil
+      end
+    end
+
+    def add_comment!(ticket:, actor:, body:, visibility: "team", correlation_id: nil)
+      Authorization.authorize!(actor, "ticket.comment")
+      redacted, count = Redactor.redact_with_count(body.to_s)
+      Comment.transaction do
+        comment = ticket.comments.create!(body: redacted, actor_type: actor.type, actor_id: actor.id, actor_name: actor.label, visibility: visibility)
+        EventStore.append!(type: "ticket.commented", aggregate: ticket, ticket: ticket, actor: actor, correlation_id: correlation_id,
+                           payload: { comment_id: comment.id, excerpt: redacted.truncate(160) })
+        if count.positive?
+          EventStore.append!(type: "security.secret_redacted", aggregate: ticket, ticket: ticket, actor: actor,
+                             payload: { where: "comment", redactions: count })
+        end
+        comment
+      end
+    end
+
+    def add_criterion!(ticket:, actor:, description:, verification_kind: "manual")
+      Authorization.authorize!(actor, "ticket.write")
+      AcceptanceCriterion.transaction do
+        c = ticket.acceptance_criteria.create!(description: description, verification_kind: verification_kind)
+        EventStore.append!(type: "ticket.criterion_added", aggregate: ticket, ticket: ticket, actor: actor, payload: { criterion_id: c.id, description: description })
+        c
+      end
+    end
+
+    # Humans verify/waive criteria; agents may only *propose* via comments.
+    def set_criterion_state!(criterion:, actor:, state:, evidence_id: nil)
+      raise Error.forbidden("Only humans can verify acceptance criteria") unless actor.human? || actor.system?
+      Authorization.authorize!(actor, "ticket.write")
+      raise Error.validation_failed("Unknown criterion state") unless AcceptanceCriterion::STATES.include?(state)
+
+      ticket = criterion.ticket
+      if evidence_id.present? && !Artifact.where(id: evidence_id, ticket_id: ticket.id).exists? && !VerificationResult.where(id: evidence_id).exists?
+        raise Error.validation_failed("Evidence #{evidence_id} is not linked to #{ticket.key}")
+      end
+      AcceptanceCriterion.transaction do
+        criterion.update!(state: state, evidence_id: evidence_id, verified_by: actor.label, verified_at: (state == "pending" ? nil : Time.current))
+        EventStore.append!(type: "ticket.criterion_#{state}", aggregate: ticket, ticket: ticket, actor: actor,
+                           payload: { criterion_id: criterion.id, evidence_id: evidence_id })
+        criterion
+      end
+    end
+
+    def add_dependency!(ticket:, depends_on:, actor:, kind: "blocks")
+      Authorization.authorize!(actor, "ticket.write")
+      TicketDependency.transaction do
+        dep = ticket.dependencies.create!(depends_on_ticket: depends_on, kind: kind)
+        EventStore.append!(type: "ticket.dependency_added", aggregate: ticket, ticket: ticket, actor: actor,
+                           payload: { depends_on: depends_on.key, kind: kind })
+        dep
+      end
+    end
+
+    def reorder!(ticket:, actor:, position:)
+      Authorization.authorize!(actor, "ticket.write")
+      ticket.update_columns(position: position.to_f, updated_at: Time.current)
+    end
+  end
+end

data/app/services/agentboard/verification_service.rb

@@ -0,0 +1,60 @@
+module Agentboard
+  # Runs catalog commands and persists results bound to the tested commit (spec §29.1).
+  module VerificationService
+    module_function
+
+    def run_catalog!(execution:, chdir:, names: nil, cancel_check: nil, timeout: nil)
+      catalog = Agentboard.config.verification_catalog
+      runner = Verification::Runner.new(catalog: catalog)
+      (names || catalog.names).map do |name|
+        cmd = catalog.fetch(name)
+        record = VerificationResult.create!(execution: execution, ticket_id: execution.ticket_id, name: name, status: "running",
+                                            required: cmd.required, command_digest: cmd.digest,
+                                            commit_sha: Git::Repository.new(chdir).head_sha(chdir: chdir), started_at: Time.current)
+        EventStore.append!(type: "verification.started", aggregate: execution, ticket: execution.ticket, execution: execution,
+                           payload: { name: name, result_id: record.id, commit_sha: record.commit_sha })
+        outcome = runner.run(name, chdir: chdir, cancel_check: cancel_check, timeout: timeout)
+        log = write_log(execution, name, outcome.output)
+        record.update!(status: outcome.status, exit_code: outcome.exit_code, commit_sha: outcome.commit_sha,
+                       output_excerpt: outcome.output.to_s.last(4000), duration_seconds: outcome.duration,
+                       finished_at: Time.current, log_artifact_id: log&.id)
+        EventStore.append!(type: "verification.#{outcome.status == "passed" ? "passed" : "failed"}", aggregate: execution,
+                           ticket: execution.ticket, execution: execution,
+                           payload: { name: name, result_id: record.id, status: outcome.status, exit_code: outcome.exit_code,
+                                      commit_sha: outcome.commit_sha, duration: outcome.duration.round(2) })
+        record
+      end
+    end
+
+    # Passive/manual flow: verify the project's checked-out HEAD (e.g. after a developer's
+    # own Claude/Codex session). Creates a `verify` execution so results have an owner.
+    def verify_repository!(ticket:, actor:, names: nil)
+      Authorization.authorize!(actor, "execution.start")
+      root = ticket.project.root_path
+      repo = Git::Repository.new(root)
+      head = repo.head_sha
+      execution = Execution.create!(ticket: ticket, provider_key: "local", action: "verify", status: "verifying",
+                                    attempt: Execution.next_attempt_for(ticket), base_sha: head, head_sha: head,
+                                    worktree_path: root, started_at: Time.current,
+                                    metadata: { "requested_by" => actor.label, "dirty" => !repo.clean? })
+      EventStore.append!(type: "verification.requested", aggregate: execution, ticket: ticket, execution: execution, actor: actor,
+                         payload: { head_sha: head, dirty: !repo.clean? })
+      results = run_catalog!(execution: execution, chdir: root, names: names)
+      required_ok = results.select(&:required).all?(&:passed?)
+      Executions.transition!(execution, required_ok ? "completed" : "failed", failure_code: (required_ok ? nil : "verification_failed"))
+      results
+    end
+
+    def write_log(execution, name, output)
+      dir = Agentboard.config.root_path.join(".agentboard", "logs", execution.id)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      path = dir.join("verify-#{name}.log")
+      File.write(path, output.to_s)
+      Artifact.create!(ticket: execution.ticket, execution: execution, kind: "test_report", uri: "file:#{path}",
+                       title: "#{name} output", sha256: Digest::SHA256.hexdigest(output.to_s), provenance: "confirmed",
+                       metadata: { name: name })
+    rescue SystemCallError
+      nil
+    end
+  end
+end