reanimator 0.1.0

data/lib/reanimator/portfolio.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The set of repositories visible to one installation, grouped for triage and
+  # stewardship (specification section 02). Building a portfolio is the very
+  # first onboarding step (section 03 stage 1): classify before acting. It is
+  # read-only and never preselects everything - the recommended set is the
+  # small, high-confidence group of active originals (section 04 default).
+  class Portfolio
+    # One repository plus how intake classified it.
+    Entry = Struct.new(:repository, :classification) do
+      def name = repository.name
+
+      def cohort = classification.cohort
+
+      def suggested_intent = classification.suggested_intent
+
+      def recommended? = classification.recommended_for_onboarding?
+    end
+
+    attr_reader :entries
+
+    def initialize(entries)
+      @entries = entries
+    end
+
+    # Classifies each path that is a repository, skipping the rest.
+    # @param paths [Array<String>]
+    # @return [Portfolio]
+    def self.scan(paths)
+      entries = paths.filter_map do |path|
+        repository = begin
+          Repository.at(path)
+        rescue RepositoryError
+          Reanimator.logger.warn("Skipping #{path.inspect}: not a repository.")
+          nil
+        end
+        next unless repository
+
+        Entry.new(repository: repository, classification: Classifier.new(repository).classify)
+      end
+
+      new(entries)
+    end
+
+    def size = entries.size
+
+    # @return [Array<Entry>] repositories recommended for active onboarding
+    def recommended = entries.select(&:recommended?)
+
+    # Entries grouped by cohort, in the canonical cohort order.
+    # @return [Hash{Symbol=>Array<Entry>}]
+    def by_cohort
+      Cohort::ALL.keys.each_with_object({}) do |key, grouped|
+        found = entries.select { |e| e.cohort.key == key }
+        grouped[key] = found unless found.empty?
+      end
+    end
+
+    def to_h
+      {
+        size: size,
+        recommended: recommended.map(&:name),
+        cohorts: by_cohort.transform_values { |es| es.map(&:name) }
+      }
+    end
+  end
+end

data/lib/reanimator/portfolio_drift.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Reanimator
+  # Configuration drift across a whole portfolio (section 06 applied to the
+  # portfolio of section 04). One repository's drift is a question; a
+  # portfolio's is a triage list, so the entries sort themselves into what
+  # needs a human, what changed harmlessly, what is unchanged, and what was
+  # never recorded in the first place.
+  #
+  # A portfolio run is never stopped by one bad member: a repository that
+  # cannot be read, or whose snapshot cannot be parsed, becomes a failed entry
+  # and the rest still report.
+  class PortfolioDrift
+    # One repository's outcome. `report` is nil when nothing has been recorded
+    # for that repository yet, which is a finding in its own right rather than
+    # a quiet pass.
+    Entry = Struct.new(:name, :report, :snapshot, :recorded_to, :error) do
+      # Compare one repository against whatever the store has on record. The
+      # entry builds itself because it is the thing that knows its own shape -
+      # both a portfolio scan and a single-repository run want exactly this.
+      #
+      # @param path [String] a repository root on disk
+      # @param store [SnapshotStore]
+      # @param record [Boolean] write the current snapshot after comparing
+      # @param intent [Symbol, nil]
+      # @return [Entry]
+      def self.for(path, store:, record: false, intent: nil)
+        repository = Repository.at(path)
+        repository.intent = intent if intent
+        current = ContractSnapshot.of(EffectivePolicyResolver.new(repository).resolve)
+        # Loaded before anything is written, so recording and comparing in one
+        # pass still compares against what was previously on record.
+        previous = store.load(repository)
+
+        new(
+          name: repository.full_name,
+          report: previous && DriftDetector.between(previous, current),
+          snapshot: current,
+          recorded_to: (store.save(current, repository) if record)
+        )
+      rescue Reanimator::Error => e
+        new(name: File.basename(File.expand_path(path)), error: e.message)
+      end
+
+      def failed? = !error.nil?
+
+      def recorded? = !report.nil?
+
+      def requires_review? = recorded? && report.requires_review?
+
+      def drifted? = recorded? && report.drifted?
+
+      # Changed, but only in ways that prove the same or more than before.
+      def benign? = drifted? && !requires_review?
+
+      def unchanged? = recorded? && !drifted?
+
+      # Nothing to compare against: not a pass, just an absence.
+      def unrecorded? = !recorded? && !failed?
+    end
+
+    # @param paths [Array<String>] repository roots on disk
+    # @param store [SnapshotStore]
+    # @param record [Boolean] write each repository's current snapshot
+    # @param intent [Symbol, nil] override the inferred lifecycle intent
+    # @return [PortfolioDrift]
+    def self.scan(paths, store: SnapshotStore.new, record: false, intent: nil, name: "portfolio")
+      entries = Array(paths).map { |path| Entry.for(path, store: store, record: record, intent: intent) }
+      new(entries: entries, name: name, store: store)
+    end
+
+    attr_reader :entries, :name, :store, :generated_at
+
+    def initialize(entries:, name: "portfolio", store: SnapshotStore.new, generated_at: nil)
+      @entries = entries
+      @name = name
+      @store = store
+      @generated_at = generated_at || Time.now
+    end
+
+    def policy_changed = entries.select(&:requires_review?)
+
+    def benign = entries.select(&:benign?)
+
+    def unchanged = entries.select(&:unchanged?)
+
+    def unrecorded = entries.select(&:unrecorded?)
+
+    def failed = entries.select(&:failed?)
+
+    # Whether anything in the portfolio asks for a human - what a CI gate keys
+    # off. Benign change does not count, and nor does a repository with nothing
+    # recorded yet: that is a known first-run state the report names plainly.
+    # A repository whose snapshot could not be *read* does count. "We could not
+    # tell" is not "nothing changed", and corrupting a snapshot file must never
+    # be a way to pass.
+    def requires_review? = policy_changed.any? || failed.any?
+
+    def to_h
+      {
+        portfolio: name,
+        generated_at: generated_at.iso8601,
+        requires_review: requires_review?,
+        tally: {
+          policy_changed: policy_changed.size, benign: benign.size,
+          unchanged: unchanged.size, unrecorded: unrecorded.size, failed: failed.size
+        },
+        repositories: entries.map { |entry| entry_hash(entry) }
+      }
+    end
+
+    private
+
+    def entry_hash(entry)
+      {repository: entry.name, error: entry.error, drift: entry.report&.to_h}.compact
+    end
+  end
+end

data/lib/reanimator/profile_inference.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Chooses the vitality profile a repository most likely wants, from its
+  # discovered facts (specification section 06). The choice is a suggestion,
+  # not a decision - it is preselected and shown with its reasoning, and an
+  # owner-declared profile always wins over it (handled in the resolver).
+  module ProfileInference
+    module_function
+
+    # @param discovery [DiscoveryResult]
+    # @return [DiscoveryResult::Suggestion]
+    def call(discovery)
+      if discovery.fact?(:rails_app)
+        suggest(:"rails-app", :high, "config/application.rb boots Rails.")
+      elsif discovery.fact?(:fork_of)
+        suggest(:"maintained-fork", :high, "The repository is a fork with an upstream.")
+      elsif discovery.fact?(:ruby_gem)
+        if discovery.fact?(:executables)
+          suggest(:"ruby-cli", :high, "A gemspec plus shipped executables indicate a CLI.")
+        else
+          suggest(:"ruby-gem", :high, "A gemspec indicates a published gem.")
+        end
+      elsif discovery.fact?(:bundler)
+        suggest(:generic, :medium, "A Ruby project without a gemspec or Rails app; using the generic profile.")
+      else
+        suggest(:generic, :low, "No strong ecosystem signal; using the generic profile.")
+      end
+    end
+
+    def suggest(profile, confidence, reason)
+      DiscoveryResult::Suggestion.new(
+        profile: profile, confidence: Confidence[confidence], reason: reason
+      )
+    end
+  end
+end

data/lib/reanimator/profiles.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The registry of built-in vitality profiles. These are the "reusable
+  # bundles of obligations for a common project shape" from section 02, seeded
+  # with the ecosystems the specification prioritizes for v1 (Ruby and Rails,
+  # section 20). Each profile's criteria are *defaults*: discovery fills in the
+  # actual commands a repository uses, and anything a profile expects but
+  # discovery cannot find is surfaced as missing proof rather than assumed.
+  module Profiles
+    module_function
+
+    # @param id [Symbol, String]
+    # @return [VitalityProfile]
+    # @raise [UnknownError] when no such profile is registered
+    def fetch(id)
+      all.fetch(id.to_sym) do
+        raise UnknownError, "Unknown vitality profile #{id.inspect}. Known: #{all.keys.join(", ")}."
+      end
+    end
+
+    def registered?(id) = all.key?(id.to_sym)
+
+    def ids = all.keys
+
+    # @return [Hash{Symbol=>VitalityProfile}]
+    def all
+      @all ||= build.freeze
+    end
+
+    # Convenience for building a criterion with profile-friendly defaults.
+    def criterion(id, claim, evaluator:, run: nil, target: nil, required: true, risk_class: :normal)
+      AcceptanceCriterion.new(
+        id: id, claim: claim, evaluator: evaluator, run: run, target: target,
+        required: required, owner: "profile", risk_class: risk_class
+      )
+    end
+
+    def build
+      {
+        generic: VitalityProfile.new(
+          id: :generic,
+          summary: "Any repository: documented, licensed, and readable.",
+          criteria: [
+            criterion(:documented, "Project has a README.", evaluator: :documentation_check, target: "README", required: false),
+            criterion(:licensed, "Project declares a license.", evaluator: :documentation_check, target: "LICENSE", required: false)
+          ]
+        ),
+        "ruby-gem": VitalityProfile.new(
+          id: :"ruby-gem",
+          summary: "A published Ruby gem: resolves, tests, lints, and builds.",
+          criteria: [
+            criterion(:dependencies, "Dependencies resolve.", evaluator: :command, run: "bundle check"),
+            criterion(:tests, "Test suite passes.", evaluator: :command, run: "bundle exec rake spec"),
+            criterion(:lint, "Lint passes.", evaluator: :command, run: "bundle exec standardrb", required: false),
+            criterion(:build, "Gem builds.", evaluator: :command, run: "gem build *.gemspec"),
+            criterion(:support_matrix, "Declared Ruby versions are exercised.", evaluator: :support_matrix, required: false)
+          ]
+        ),
+        "ruby-cli": VitalityProfile.new(
+          id: :"ruby-cli",
+          summary: "A Ruby command-line tool: everything a gem needs plus a runnable executable.",
+          inherits: [:"ruby-gem"],
+          criteria: [
+            criterion(:executable, "Executable boots and answers --help.", evaluator: :command, required: false)
+          ]
+        ),
+        "web-application": VitalityProfile.new(
+          id: :"web-application",
+          summary: "A deployable web application that must boot and answer a health endpoint.",
+          criteria: [
+            criterion(:boot, "Application boots and answers its health endpoint.", evaluator: :http_smoke, target: "/up")
+          ]
+        ),
+        "rails-app": VitalityProfile.new(
+          id: :"rails-app",
+          summary: "A maintained Rails application: tests, assets, and boot.",
+          inherits: [:"web-application"],
+          criteria: [
+            criterion(:tests, "Test suite passes.", evaluator: :command, run: "bin/rails test"),
+            criterion(:assets, "Frontend assets build.", evaluator: :command, run: "yarn build", required: false)
+          ]
+        ),
+        "rails-legacy": VitalityProfile.new(
+          id: :"rails-legacy",
+          summary: "A historical Rails application preserved for readability and provenance.",
+          criteria: [
+            criterion(:"source-readable", "Source remains readable with intact history.", evaluator: :repository_integrity),
+            criterion(:"reproduction-documented", "Reproduction instructions are documented.", evaluator: :documentation_check, target: "README")
+          ]
+        ),
+        "maintained-fork": VitalityProfile.new(
+          id: :"maintained-fork",
+          summary: "A maintained fork tracked for upstream divergence and unique commits.",
+          criteria: [
+            criterion(:divergence, "Unique commits and upstream divergence are known.", evaluator: :repository_integrity, required: false)
+          ]
+        ),
+        "constrained-hardware": VitalityProfile.new(
+          id: :"constrained-hardware",
+          summary: "A hardware- or credential-dependent project verified within declared boundaries.",
+          criteria: [
+            criterion(:"unit-tests", "Unit tests pass on hosted runners.", evaluator: :command, run: "bundle exec rake test"),
+            criterion(:"package-build", "Package builds.", evaluator: :command, run: "gem build *.gemspec")
+          ]
+        )
+      }
+    end
+  end
+end

data/lib/reanimator/proof_of_life.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Computes a repository's proof-of-life state from its baseline results and
+  # its lifecycle intent (specification section 15). The rules encode two
+  # non-negotiables: a failing required check is never green, and a claim
+  # without executable evidence is Unproven rather than Alive. Intent shapes
+  # the reading - a preserved artifact that proves its integrity is Sleeping,
+  # not Alive, because it is intentionally not actively maintained.
+  module ProofOfLife
+    module_function
+
+    # @param contract [EffectiveContract]
+    # @param results [Array<CriterionResult>]
+    # @return [RepositoryState]
+    def assess(contract, results)
+      required = results.select(&:required?)
+      failed = required.select(&:failed?)
+      unproven = required.select(&:unproven?)
+      intent = contract.intent.to_sym
+
+      RepositoryState.fetch(state_key(intent, failed, unproven))
+    end
+
+    def state_key(intent, failed, unproven)
+      return :retired if intent == :retire
+
+      if failed.any?
+        :at_risk
+      elsif unproven.any?
+        (intent == :upstream) ? :sleeping : :unproven
+      else
+        proven_state(intent)
+      end
+    end
+
+    # State for a repository whose required criteria are all verified.
+    def proven_state(intent)
+      case intent
+      when :maintain, :incubate then :alive
+      else :sleeping # monitor, preserve, upstream, ignore
+      end
+    end
+  end
+end

data/lib/reanimator/proposed_change.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Reanimator
+  # A repair that has been produced and independently verified but **not
+  # submitted** (specification section 11 autonomy ladder: repair creates a
+  # bounded patch "with no repository write required until submission"). It
+  # carries everything a draft pull request would need - branch name, patch,
+  # title, and body - so submission becomes a separate, explicitly authorized
+  # step rather than a side effect of repair.
+  class ProposedChange
+    attr_reader :obligation, :patch, :plan, :pre_state, :post_state
+
+    def initialize(obligation:, patch:, plan:, pre_state:, post_state:)
+      @obligation = obligation
+      @patch = patch
+      @plan = plan
+      @pre_state = pre_state
+      @post_state = post_state
+    end
+
+    # A deterministic branch name derived from the obligation and the patch, so
+    # the same repair maps to the same branch (idempotence).
+    def branch
+      slug = obligation.target.id.to_s.gsub(/[^a-z0-9]+/i, "-")
+      fingerprint = Digest::SHA256.hexdigest(patch.paths.sort.join(","))[0, 8]
+      "reanimator/repair-#{slug}-#{fingerprint}"
+    end
+
+    def title
+      "Fix: #{obligation.target.claim}"
+    end
+
+    def body
+      <<~BODY.strip
+        Reanimator proposes this bounded repair for `#{obligation.target.id}`.
+
+        Objective: #{obligation.target.claim}
+        Result: #{pre_state} → #{post_state} (independently verified)
+        Files: #{patch.paths.join(", ")}
+
+        #{plan}
+
+        This change was produced by an isolated agent and graded by Reanimator's
+        own evaluators; the agent did not grade its own work. Merge remains a
+        human decision.
+      BODY
+    end
+
+    def to_h
+      {branch: branch, title: title, files: patch.paths, pre_state: pre_state, post_state: post_state}
+    end
+  end
+end

data/lib/reanimator/provenance.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The audit trail behind a single discovered fact (specification section
+  # 06): its source, how it was extracted, and when. Provenance is what lets
+  # the interface always answer "Why does Reanimator believe this?" - no
+  # fact exists in the system without one.
+  class Provenance
+    # @return [String] the concrete evidence, e.g. "reanimator.gemspec" or
+    #   ".github/workflows/main.yml"
+    attr_reader :source
+    # @return [Symbol] extraction method, e.g. :file_present, :yaml_key,
+    #   :regex_match, :git_metadata
+    attr_reader :method
+    # @return [String, nil] a short human-readable justification/excerpt
+    attr_reader :detail
+    # @return [Time] when the fact was extracted
+    attr_reader :detected_at
+
+    def initialize(source:, method:, detail: nil, detected_at: Time.now)
+      @source = source
+      @method = method.to_sym
+      @detail = detail
+      @detected_at = detected_at
+      freeze
+    end
+
+    # A one-line, human-facing explanation of the evidence.
+    # @return [String]
+    def explanation
+      base = "#{source} (#{method})"
+      detail ? "#{base}: #{detail}" : base
+    end
+
+    def to_h
+      {source: source, method: method, detail: detail, detected_at: detected_at.iso8601}
+    end
+  end
+end

data/lib/reanimator/relationship.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A typed edge between two repositories (specification section 10). Related
+  # projects are a compatibility graph, not isolated automation targets, so an
+  # edge is a first-class value: it names *what kind* of dependence exists, and
+  # it is what a family failure points at - "the exact edge that broke, not
+  # merely the repository that ran CI".
+  class Relationship
+    TYPES = {
+      compatibility_suite: "A separate executable suite that validates this project's public claims.",
+      plugin_for: "An integration that must remain compatible with a host project or SDK.",
+      deployment_example: "A deployment example that must build against its parent project.",
+      portfolio_index: "An index or profile that should reflect active project metadata.",
+      shared_library: "A package whose releases trigger downstream compatibility checks.",
+      fork_of: "A maintained fork whose unique commits and upstream divergence matter.",
+      documentation_for: "Documentation whose examples and links must stay synchronized."
+    }.freeze
+
+    # The member role each downstream relationship implies.
+    ROLES = {
+      compatibility_suite: :compatibility_suite,
+      plugin_for: :plugin,
+      deployment_example: :deployment_example,
+      portfolio_index: :index,
+      shared_library: :library,
+      fork_of: :fork,
+      documentation_for: :documentation
+    }.freeze
+
+    # @return [String] the downstream repository (the dependent side)
+    attr_reader :from
+    # @return [String] the upstream repository it depends on
+    attr_reader :to
+    # @return [Symbol] one of {TYPES}
+    attr_reader :type
+    # @return [String, nil] why this edge is believed
+    attr_reader :evidence
+
+    def initialize(from:, to:, type:, evidence: nil)
+      @type = type.to_sym
+      unless TYPES.key?(@type)
+        raise UnknownError, "Unknown relationship type #{type.inspect}. Known: #{TYPES.keys.join(", ")}."
+      end
+
+      @from = from
+      @to = to
+      @evidence = evidence
+      freeze
+    end
+
+    def description = TYPES.fetch(type)
+
+    # The role the dependent side plays inside its family.
+    def role = ROLES.fetch(type, :member)
+
+    # A single, unambiguous name for this edge - what a family failure reports.
+    def label = "#{to} -> #{from} (#{type.to_s.tr("_", " ")})"
+
+    def to_h = {from: from, to: to, type: type, evidence: evidence}.compact
+  end
+end

data/lib/reanimator/repair_run.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Reanimator
+  # Orchestrates one bounded repair, end to end, without writing to the
+  # repository (specification section 11 repair rung, section 17 run). The flow
+  # is: baseline to find a failing obligation, check the permission model,
+  # route to a ready agent, let it propose a patch in an isolated workspace,
+  # apply that patch to a *separate* clean copy, re-evaluate independently, and
+  # only then materialize a proposed draft PR. Every exit is a recorded {Run}.
+  class RepairRun
+    REQUIRED_CAPABILITIES = [Agents::Capability::PATCH, Agents::Capability::REPOSITORY_EDIT].freeze
+    EDITABLE = ["lib/**", "app/**", "*.rb"].freeze
+
+    def initialize(contract, provider: :local, task_class: :patch_dependency, trigger: "user request")
+      @contract = contract
+      @provider = provider.to_sym
+      @task_class = task_class.to_sym
+      @trigger = trigger
+    end
+
+    # @return [Run]
+    def run
+      pre = BaselineRunner.new(@contract, execute: true).run
+      target = pre.first_failing_required_criterion
+      return record(:no_op, pre: pre, reason: "All required criteria pass; no repair is needed.") unless target
+
+      resolution = PermissionModel.new(@contract).resolve(@task_class)
+      unless resolution.permits?(:repair)
+        return record(:escalation, pre: pre, objective: target,
+          reason: "Repair is not enabled for #{@task_class} (max autonomy #{resolution.max_action}); enable repair to proceed.")
+      end
+
+      decision = route
+      unless decision.selected?
+        return record(:safe_stop, pre: pre, objective: target, reason: "No ready agent. #{decision.explanation}")
+      end
+
+      attempt(pre, target, decision.profile)
+    end
+
+    private
+
+    def attempt(pre, target, profile)
+      adapter = Agents.for(profile.connection)
+      workspace = Isolation.copy(@contract.repository.path)
+      begin
+        task = build_task(target, workspace, pre)
+        result = adapter.repair(task)
+        unless result.structured?
+          return record(:safe_stop, pre: pre, objective: target, provider: adapter.provider,
+            reason: result.message || "The agent produced no structured plan and patch.")
+        end
+
+        breach = result.patch.paths.reject { |path| task.may_edit?(path) }
+        unless breach.empty?
+          return record(:escalation, pre: pre, objective: target, provider: adapter.provider,
+            reason: "Refused: the patch touches protected or out-of-scope paths: #{breach.join(", ")}.")
+        end
+
+        verify(pre, target, adapter, result)
+      ensure
+        FileUtils.remove_entry(workspace, true)
+      end
+    end
+
+    def verify(pre, target, adapter, result)
+      post = evaluate_isolated(result.patch)
+      if resolved?(target, pre, post)
+        change = ProposedChange.new(
+          obligation: obligation(target), patch: result.patch, plan: result.plan,
+          pre_state: pre.state.to_sym, post_state: post.state.to_sym
+        )
+        record(:draft_pr, pre: pre, post: post, objective: target, provider: adapter.provider,
+          proposed_change: change, cost: result.cost_usd, tools: result.tool_use)
+      else
+        record(:report, pre: pre, post: post, objective: target, provider: adapter.provider,
+          cost: result.cost_usd, reason: "The repair did not independently verify; not proposing a change.")
+      end
+    end
+
+    # Apply the patch to a fresh, clean copy and grade it there - never in the
+    # agent's workspace (verifier isolation, section 09).
+    def evaluate_isolated(patch)
+      Isolation.copy(@contract.repository.path) do |eval_dir|
+        patch.apply(eval_dir)
+        BaselineRunner.new(EffectivePolicyResolver.new(Repository.at(eval_dir)).resolve, execute: true).run
+      end
+    end
+
+    def resolved?(target, pre, post)
+      return false unless post.result_for(target.id)&.verified?
+
+      # No criterion that was verified-required before may be unresolved after.
+      regressed = pre.verified_required_ids & post.unresolved_required.map { |r| r.criterion.id }
+      regressed.empty?
+    end
+
+    # Readiness is *proven*, not assumed: the provider is commissioned against a
+    # disposable fixture and its verdict (ready/degraded/incompatible/unavailable)
+    # decides eligibility. Only a commissioned-ready provider is routed to; any
+    # other verdict fails closed to a safe stop.
+    def route
+      adapter = Agents.for(connection)
+      readiness = Commissioning::Test.new(adapter).run.readiness
+      profile = AgentProfile.from_adapter(adapter, readiness: readiness)
+      Routing::Router.new([profile]).select(required_capabilities: REQUIRED_CAPABILITIES, task_class: @task_class)
+    end
+
+    def build_task(target, workspace, pre)
+      Agents::RepairTask.new(
+        objective: target, workspace: workspace, evidence: pre,
+        constraints: Agents::Constraints.new(
+          allowed_paths: EDITABLE, protected_paths: @contract.protected_paths,
+          max_cost_usd: connection.max_cost_usd, code_egress: Agents.for(connection).code_egress
+        )
+      )
+    end
+
+    def obligation(target)
+      Obligation.new(
+        repository: @contract.repository, policy_version: @contract.policy_version,
+        target: target, trigger: @trigger, task_class: @task_class
+      )
+    end
+
+    def connection
+      @connection ||=
+        if @provider == :local
+          AgentConnection.local
+        else
+          AgentConnection.new(provider: @provider, credentials_ref: Reanimator::CREDENTIAL_REFS[@provider])
+        end
+    end
+
+    def record(outcome, pre: nil, post: nil, objective: nil, provider: nil, proposed_change: nil, cost: 0.0, tools: [], reason: nil)
+      Run.new(
+        outcome: outcome, repository: @contract.repository, policy_version: @contract.policy_version,
+        trigger: @trigger, objective: objective, provider: provider, access: {tools: tools},
+        pre_state: pre&.state&.to_sym, post_state: post&.state&.to_sym,
+        cost_usd: cost, proposed_change: proposed_change, reason: reason
+      )
+    end
+  end
+end