ace-overseer 0.17.0 → 0.18.2

data/lib/ace/overseer/molecules/preservation_manifest.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "open3"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Strict parser for the optional `--preservation FILE` manifest.
+      #
+      # FILE is a claim to verify, never authorization or proof by itself.
+      # Schema: `version: 1` plus `candidates:`; each record declares the
+      # cross-repository destination that received a candidate's work:
+      #
+      #   - worktree_path: the candidate worktree the record belongs to
+      #   - source_repo / source_base / source_head: the candidate's common
+      #     repository and the claimed work range
+      #   - destination_repo / destination_base / destination_head /
+      #     destination_branch: where the work was transferred
+      #
+      # Paths must be local absolute repositories and revisions must resolve
+      # to exact commits. Duplicate worktree entries, entries pointing at the
+      # source checkout itself, and unresolvable revisions fail before any
+      # apply action.
+      class PreservationManifest
+        REQUIRED_FIELDS = %w[
+          worktree_path
+          source_repo
+          source_base
+          source_head
+          destination_repo
+          destination_base
+          destination_head
+          destination_branch
+        ].freeze
+
+        Record = Struct.new(
+          :worktree_path, :source_repo, :source_base, :source_head,
+          :destination_repo, :destination_base, :destination_head, :destination_branch,
+          :resolved_source_base, :resolved_source_head,
+          :resolved_destination_base, :resolved_destination_head, :resolved_destination_branch_tip,
+          keyword_init: true
+        ) do
+          def destination_branch_name
+            destination_branch.sub(%r{\Arefs/heads/}, "")
+          end
+        end
+
+        class Invalid < Ace::Overseer::Error; end
+
+        # @param path [String] Manifest file path
+        # @param git_runner [Proc] `->(repo, *args) { [stdout, stderr, status] }`
+        # @return [PreservationManifest]
+        def self.load(path, git_runner: method(:default_git_runner))
+          raise Invalid, "Preservation manifest not found: #{path}" unless File.file?(path.to_s)
+
+          data = begin
+            YAML.safe_load_file(path, permitted_classes: [Time, Date])
+          rescue Psych::SyntaxError, Psych::Exception => e
+            raise Invalid, "Preservation manifest is not valid YAML: #{e.message}"
+          end
+          unless data.is_a?(Hash)
+            raise Invalid, "Preservation manifest must be a YAML mapping"
+          end
+
+          version = data["version"]
+          unless version == 1
+            raise Invalid, "Preservation manifest requires `version: 1` (got #{version.inspect})"
+          end
+
+          candidates = data["candidates"]
+          unless candidates.is_a?(Array)
+            raise Invalid, "Preservation manifest requires a `candidates` list"
+          end
+
+          new(parse_candidates(candidates, git_runner: git_runner))
+        end
+
+        def self.default_git_runner(repo, *args)
+          Open3.capture3("git", "-C", repo, *args)
+        end
+        private_class_method :default_git_runner
+
+        def self.parse_candidates(entries, git_runner:)
+          records = entries.map.with_index(1) do |entry, index|
+            parse_record(entry, index, git_runner: git_runner)
+          end
+
+          duplicate = records.group_by(&:worktree_path).select { |_path, group| group.length > 1 }
+          unless duplicate.empty?
+            raise Invalid, "Preservation manifest has duplicate entries for #{duplicate.keys.join(", ")}"
+          end
+
+          records
+        end
+        private_class_method :parse_candidates
+
+        def self.parse_record(entry, index, git_runner:)
+          unless entry.is_a?(Hash)
+            raise Invalid, "Preservation manifest candidate #{index} must be a mapping"
+          end
+
+          unknown = entry.keys.map(&:to_s) - REQUIRED_FIELDS
+          unless unknown.empty?
+            raise Invalid, "Preservation manifest candidate #{index} has unknown fields: #{unknown.join(", ")}"
+          end
+
+          missing = REQUIRED_FIELDS.select { |field| entry[field].nil? || entry[field].to_s.strip.empty? }
+          unless missing.empty?
+            raise Invalid, "Preservation manifest candidate #{index} is missing: #{missing.join(", ")}"
+          end
+
+          attrs = REQUIRED_FIELDS.to_h { |field| [field.to_sym, entry[field].to_s] }
+          require_absolute_repository(attrs[:worktree_path], "worktree_path", index)
+          require_absolute_repository(attrs[:source_repo], "source_repo", index)
+          require_absolute_repository(attrs[:destination_repo], "destination_repo", index)
+          require_real_repository(attrs[:source_repo], "source_repo", index)
+          require_real_repository(attrs[:destination_repo], "destination_repo", "destination")
+
+          if same_path?(attrs[:worktree_path], attrs[:destination_repo])
+            raise Invalid,
+              "Preservation manifest candidate #{index}: the source checkout #{attrs[:worktree_path]} is " \
+              "scheduled for deletion and cannot be its own surviving destination"
+          end
+
+          record = Record.new(**attrs)
+          record.resolved_source_base = resolve_revision(record.source_repo, record.source_base, "source_base", index, git_runner)
+          record.resolved_source_head = resolve_revision(record.source_repo, record.source_head, "source_head", index, git_runner)
+          record.resolved_destination_base = resolve_revision(record.destination_repo, record.destination_base, "destination_base", index, git_runner)
+          record.resolved_destination_head = resolve_revision(record.destination_repo, record.destination_head, "destination_head", index, git_runner)
+          record.resolved_destination_branch_tip = resolve_branch_tip(
+            record.destination_repo, record.destination_branch, index, git_runner
+          )
+          record
+        end
+        private_class_method :parse_record
+
+        def self.require_absolute_repository(path, field, index)
+          return if path.to_s.start_with?("/")
+
+          raise Invalid, "Preservation manifest candidate #{index}: #{field} must be an absolute path"
+        end
+        private_class_method :require_absolute_repository
+
+        def self.require_real_repository(path, field, index)
+          return if File.directory?(path)
+
+          raise Invalid, "Preservation manifest candidate #{index}: #{field} is not a directory: #{path}"
+        end
+        private_class_method :require_real_repository
+
+        def self.same_path?(left, right)
+          File.realpath(left) == File.realpath(right)
+        rescue Errno::ENOENT
+          false
+        end
+        private_class_method :same_path?
+
+        def self.resolve_revision(repo, revision, field, index, git_runner)
+          stdout, stderr, status = git_runner.call(repo, "rev-parse", "--verify", "--quiet", "#{revision}^{commit}")
+          unless status.success?
+            raise Invalid,
+              "Preservation manifest candidate #{index}: #{field} `#{revision}` does not resolve to a commit " \
+              "in #{repo}: #{stderr.to_s.strip}"
+          end
+
+          stdout.to_s.strip
+        end
+        private_class_method :resolve_revision
+
+        # The destination must be an existing branch ref — never a raw SHA,
+        # which could name the candidate's own HEAD and masquerade as a
+        # surviving destination while prune deletes the only real branch.
+        def self.resolve_branch_tip(repo, branch, index, git_runner)
+          stdout, _stderr, status = git_runner.call(repo, "rev-parse", "--verify", "--quiet", branch.to_s)
+          unless status.success?
+            raise Invalid,
+              "Preservation manifest candidate #{index}: destination_branch `#{branch}` does not resolve in #{repo}"
+          end
+
+          full_name, _stderr, name_status = git_runner.call(repo, "rev-parse", "--symbolic-full-name", branch.to_s)
+          canonical = full_name.to_s.strip
+          if !name_status.success? || !canonical.start_with?("refs/heads/")
+            raise Invalid,
+              "Preservation manifest candidate #{index}: destination_branch `#{branch}` must name an existing " \
+              "branch ref (refs/heads/...)"
+          end
+
+          stdout.to_s.strip
+        end
+        private_class_method :resolve_branch_tip
+
+        # @param records [Array<Record>] Parsed, resolved records
+        def initialize(records)
+          @records = records.freeze
+        end
+
+        attr_reader :records
+
+        # @return [Record, nil] The record declaring the given worktree
+        def for_worktree(worktree_path)
+          canonical = canonical_path(worktree_path)
+          records.find { |record| canonical_path(record.worktree_path) == canonical }
+        end
+
+        # Reject manifest entries that do not belong to any selected
+        # candidate. A record for an unselected worktree is an input error.
+        #
+        # @param selected_paths [Array<String>] Candidate worktree paths
+        # @raise [Invalid] When an entry matches no selected worktree
+        def ensure_all_match!(selected_paths)
+          selected = selected_paths.map { |path| canonical_path(path) }
+          unmatched = records.reject { |record| selected.include?(canonical_path(record.worktree_path)) }
+          return if unmatched.empty?
+
+          raise Invalid,
+            "Preservation manifest entries do not match any selected worktree: " +
+            unmatched.map(&:worktree_path).join(", ")
+        end
+
+        private
+
+        def canonical_path(path)
+          File.realpath(path)
+        rescue Errno::ENOENT
+          File.expand_path(path)
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/molecules/prune_safety_checker.rb

@@ -5,23 +5,73 @@ require "open3"
 module Ace
   module Overseer
     module Molecules
+      # Classifies one worktree candidate for prune, fail-closed.
+      #
+      # A candidate is safe only when ALL of the following hold:
+      # - the assignment queue label is completed,
+      # - the task is done (a missing task record alone proves nothing but
+      #   never authorizes removal by itself),
+      # - the checkout is clean including untracked files (dirty tracked AND
+      #   untracked files are work; --force never overrides this),
+      # - required ignored artifacts are preserved: a local evidence journal
+      #   checkout must already be contained in refs/ace/execution,
+      # - all recorded attempts are terminal (active or uncertain attempts
+      #   and unreadable attempt state block),
+      # - an executed preservation proof passes (accepted ancestry or a
+      #   verified declared destination).
       class PruneSafetyChecker
-        def initialize(context_collector: nil, task_loader_factory: nil)
+        def initialize(context_collector: nil, task_loader_factory: nil, preservation_checker: nil,
+          attempt_store_factory: nil)
           @context_collector = context_collector || WorktreeContextCollector.new
           @task_loader_factory = task_loader_factory || -> { Ace::Task::Organisms::TaskManager.new }
+          @preservation_checker = preservation_checker || GitPreservationChecker.new
+          @attempt_store_factory = attempt_store_factory || ->(cache_base) {
+            Ace::Assign::Molecules::AttemptStore.new(cache_base: cache_base)
+          }
         end
 
-        def check(worktree_path:, task_ref:)
+        attr_reader :preservation_checker
+
+        # @param worktree_path [String] Candidate worktree
+        # @param task_ref [String, nil] Task id recorded for the worktree
+        # @param manifest_record [PreservationManifest::Record, nil] Declared
+        #   destination claim for this worktree
+        # @param accepted_base [Hash, nil] `{branch:, head:}` surviving base
+        # @return [Models::PruneCandidate]
+        def check(worktree_path:, task_ref:, manifest_record: nil, accepted_base: nil)
           context = @context_collector.collect(worktree_path)
 
           assignment_complete = assignment_complete?(context.assignment_status)
           task_done = task_done?(worktree_path, task_ref)
-          git_clean = git_clean_for_prune?(worktree_path, context.git_status)
+          git_clean = git_clean_for_prune?(worktree_path)
+          artifacts_safe, artifact_reasons = required_ignored_artifacts_safe?(worktree_path)
+          attempts_terminal, attempt_reasons, recorded_base = attempts_evidence(worktree_path, context)
+          # One branch identity for the whole check: read before the proof,
+          # handed to the proof as the candidate's own branch, and verified
+          # downstream. A later read could name a switched-to destination.
+          branch_at_check = head_branch(worktree_path)
+          proof = preservation_proof(
+            worktree_path: worktree_path,
+            accepted_base: accepted_base,
+            manifest_record: manifest_record,
+            recorded_base: recorded_base,
+            candidate_branch: branch_at_check
+          )
+          # The HEAD and branch whose preservation was actually proven:
+          # destructive boundaries downstream must use these identities,
+          # never a later re-read that was itself never proven. Detachment
+          # comes from Git's symbolic HEAD state, not the branch name's
+          # shape — a 40-hex branch name is a real branch.
+          verified_head = proof.preserved? ? proof.head : nil
+          verified_branch = proof.preserved? ? branch_at_check : nil
 
           reasons = []
           reasons << "assignment not complete" unless assignment_complete
           reasons << "task not done" unless task_done
           reasons << "git not clean" unless git_clean
+          reasons.concat(artifact_reasons)
+          reasons.concat(attempt_reasons)
+          reasons << "preservation not proven: #{proof.reason}" unless proof.preserved?
 
           Models::PruneCandidate.new(
             task_id: task_ref,
@@ -29,6 +79,10 @@ module Ace
             assignment_complete: assignment_complete,
             task_done: task_done,
             git_clean: git_clean,
+            attempts_terminal: attempts_terminal && artifacts_safe,
+            preserved: proof.preserved?,
+            verified_head: verified_head,
+            verified_branch: verified_branch,
             reasons: reasons
           )
         end
@@ -46,28 +100,112 @@ module Ace
           paths.any? { |path| task_done_in_context?(path, task_ref) }
         end
 
-        def git_clean?(git_status)
-          git_status.is_a?(Hash) && (git_status["clean"] == true || git_status[:clean] == true)
+        # Full cleanliness: untracked files are work too. Ignored files are
+        # not dirt, but required ignored artifacts are checked separately.
+        def git_clean_for_prune?(worktree_path)
+          stdout, status = Open3.capture2(
+            "git", "-C", worktree_path, "status", "--porcelain"
+          )
+          return false unless status.success?
+
+          stdout.to_s.strip.empty?
+        rescue
+          false
         end
 
-        def git_clean_for_prune?(worktree_path, git_status)
-          tracked_clean = tracked_changes_clean?(worktree_path)
-          return tracked_clean unless tracked_clean.nil?
+        # A journal checkout inside the worktree is a required ignored
+        # artifact unless every journaled commit already lives in the
+        # authoritative evidence ref.
+        def required_ignored_artifacts_safe?(worktree_path)
+          checkout = File.join(worktree_path, assign_cache_relative, "evidence-checkout", "journal")
+          return [true, []] unless File.directory?(checkout)
+
+          head, status = Open3.capture2("git", "-C", checkout, "rev-parse", "HEAD")
+          checkout_head = head.to_s.strip
+          if !status.success? || checkout_head.empty?
+            return [false, ["evidence journal checkout unreadable: #{checkout}"]]
+          end
+
+          common_dir = project_git_common_dir(worktree_path)
+          if common_dir.nil?
+            return [false, ["cannot resolve common git dir to verify evidence journal"]]
+          end
 
-          git_clean?(git_status)
+          _out, evidence_status = Open3.capture2(
+            "git", "-C", common_dir, "merge-base", "--is-ancestor", checkout_head, "refs/ace/execution"
+          )
+          if evidence_status.success?
+            [true, []]
+          else
+            [false, ["evidence journal checkout has commits not in refs/ace/execution"]]
+          end
         end
 
-        def tracked_changes_clean?(worktree_path)
-          stdout, status = Open3.capture2(
-            "git", "-C", worktree_path, "status", "--porcelain", "--untracked-files=no"
+        # Attempt evidence from the worktree's own assignment cache: any
+        # active or uncertain attempt blocks; an unreadable store blocks.
+        # Returns the independently recorded creation baseline (base_head)
+        # for patch-range preservation proofs.
+        def attempts_evidence(worktree_path, context)
+          ids = Array(context.assignments).filter_map { |entry| entry.dig("assignment", "id") }
+          return [true, [], nil] if ids.empty?
+
+          cache_base = File.join(worktree_path, assign_cache_relative)
+          begin
+            store = @attempt_store_factory.call(cache_base)
+          rescue => e
+            return [false, ["attempt state unreadable: #{e.message}"], nil]
+          end
+          reasons = []
+          recorded_base = nil
+          terminal = true
+          ids.each do |assignment_id|
+            attempts = store.list(assignment_id)
+            attempts.each do |attempt|
+              recorded_base ||= attempt.binding.base_head
+              next unless attempt.active? || attempt.uncertain?
+
+              terminal = false
+              reasons << "attempt #{attempt.attempt_id} on assignment #{assignment_id} is #{attempt.state}"
+            end
+          rescue => e
+            terminal = false
+            reasons << "attempt state for assignment #{assignment_id} unreadable: #{e.message}"
+          end
+          [terminal, reasons, recorded_base]
+        end
+
+        def preservation_proof(worktree_path:, accepted_base:, manifest_record:, recorded_base:, candidate_branch: nil)
+          return Models::PreservationProof.blocked("no surviving accepted base could be resolved") if accepted_base.nil?
+
+          @preservation_checker.proof(
+            worktree_path: worktree_path,
+            accepted_base: accepted_base,
+            manifest_record: manifest_record,
+            recorded_base: recorded_base,
+            candidate_branch: candidate_branch
+          )
+        rescue => e
+          Models::PreservationProof.blocked("preservation proof failed: #{e.message}")
+        end
+
+        # The checked-out branch per Git's symbolic HEAD state; nil when
+        # detached (or unreadable — then there is no deletable ref).
+        def head_branch(worktree_path)
+          stdout, _stderr, status = Open3.capture3(
+            "git", "-C", worktree_path, "symbolic-ref", "-q", "HEAD"
           )
           return nil unless status.success?
 
-          stdout.to_s.strip.empty?
+          branch = stdout.to_s.strip.sub(/\Arefs\/heads\//, "")
+          branch.empty? ? nil : branch
         rescue
           nil
         end
 
+        def assign_cache_relative
+          Ace::Assign.config["cache_dir"] || ".ace-local/assign"
+        end
+
         def task_done_in_context?(path, task_ref)
           Dir.chdir(path) do
             manager = @task_loader_factory.call
@@ -79,15 +217,20 @@ module Ace
         end
 
         def project_root_from_worktree(worktree_path)
+          common_dir = project_git_common_dir(worktree_path)
+          return nil if common_dir.nil?
+
+          File.dirname(common_dir)
+        end
+
+        def project_git_common_dir(worktree_path)
           stdout, status = Open3.capture2(
             "git", "-C", worktree_path, "rev-parse", "--path-format=absolute", "--git-common-dir"
           )
           return nil unless status.success?
 
           common_dir = stdout.to_s.strip
-          return nil if common_dir.empty?
-
-          File.dirname(common_dir)
+          common_dir.empty? ? nil : common_dir
         rescue
           nil
         end