ace-assign 0.58.0 → 0.61.0

data/lib/ace/assign/molecules/evidence_journal.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+require "digest"
 require "fileutils"
 require "json"
 require "open3"
@@ -97,11 +99,15 @@ module Ace
           value = ref_value
           return [] if value.nil?
 
-          with_lock do
-            ensure_checkout!
-            sync_checkout(value)
-            order_by_chain(event_files(assignment_id).map { |path| JSON.parse(File.read(path)) })
+          paths, stderr, status = git("ls-tree", "-r", "--name-only", value, "--",
+            "execution/#{assignment_id}/events/")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot read journal events: #{stderr}" unless status.success?
+          events = paths.lines.map(&:strip).select { |path| path.end_with?(".json") }.map do |path|
+            content, error, read_status = git("show", "#{value}:#{path}")
+            raise AttemptErrors::EvidenceUnavailable, "Cannot read journal event: #{error}" unless read_status.success?
+            JSON.parse(content)
           end
+          order_by_chain(events)
         rescue JSON::ParserError => e
           raise AttemptErrors::EvidenceUnavailable, "Corrupt journal event for #{assignment_id}: #{e.message}"
         end
@@ -117,6 +123,215 @@ module Ace
             .compact
         end
 
+        # Reserve a globally unique service request in the same evidence ref
+        # as its owning attempt. The request index and attempt event are one
+        # Git commit, so a ref race cannot admit two effects for one ID. An
+        # exact authorization reference is consumed by its first live claim:
+        # a second request presenting the same operation/project/target
+        # authorization is rejected instead of dispatching a duplicate effect.
+        # Dispatching callers claim directly as +uncertain+ so no commit
+        # window exists where a stranded claim reads as accepted.
+        def claim_service_request(binding, state: "accepted", guard: nil)
+          guard ||= -> { authorization_conflict(binding) }
+          update_service_request(binding.fetch("request_id"), expected: nil,
+            replacement: binding.merge("state" => state, "claimed_at" => Time.now.utc.iso8601(9)),
+            event_type: "service_claim", guard: guard)
+        end
+
+        # Reject a service request. A request not yet on file gets its
+        # auditable rejection claim (which never consumed the authorization);
+        # an existing live claim transitions to rejected but stays consuming:
+        # only attributable evidence that the effect did not occur may free a
+        # dispatched authorization, never a bare rejection.
+        def reject_service_request(binding, reason:)
+          request_id = binding.fetch("request_id")
+          existing = service_request(request_id)
+          if existing
+            unless existing.except("state", "receipt", "reason", "claimed_at", "failed_at") == binding.except("state", "receipt", "reason", "claimed_at", "failed_at")
+              raise AttemptErrors::Conflict, "Service request #{request_id} has different input"
+            end
+            return existing if existing["state"] == "rejected"
+            return update_service_request(request_id, expected: existing,
+              replacement: existing.merge("state" => "rejected", "reason" => reason),
+              event_type: "service_transition")
+          end
+          update_service_request(request_id, expected: nil,
+            replacement: binding.merge("state" => "rejected", "reason" => reason, "consumed" => false),
+            event_type: "service_claim")
+        end
+
+        # Terminal writes are validated HERE at the journal boundary —
+        # receipt schema, binding against the current record, and attested
+        # outcome — so no caller-supplied flag decides trust. The
+        # coordinator additionally performs content-level attestation and
+        # file verification.
+        def transition_service_request(request_id, state:, receipt: nil, validated: false)
+          unless %w[succeeded failed uncertain rejected failed-settled].include?(state)
+            raise ArgumentError, "invalid service request state"
+          end
+          current = service_request(request_id)
+          raise AttemptErrors::NotFound, "Service request #{request_id} not found" unless current
+          # Terminal states are immutable; failed-settled is reached only
+          # from a dispatched (failed, uncertain, or consumed-rejected)
+          # effect with a validated no-effect receipt.
+          consumed_rejected = current["state"] == "rejected" && current["consumed"] != false
+          if %w[succeeded failed-settled].include?(current["state"]) ||
+              (current["state"] == "rejected" && !consumed_rejected) ||
+              (consumed_rejected && state != "failed-settled")
+            raise AttemptErrors::InvalidState, "Service request #{request_id} is terminal"
+          end
+          validate_terminal_receipt!(current, state, receipt) if terminal_state?(state)
+          stamped = current.merge("state" => state, "receipt" => receipt)
+          stamped["failed_at"] = Time.now.utc.iso8601(9) if state == "failed"
+          update_service_request(request_id, expected: current,
+            replacement: stamped,
+            event_type: "service_transition")
+        end
+
+        TERMINAL_RECEIPT_FIELDS = %w[assignment_id attempt_id candidate_head evidence executor_uid
+          input_digest operation outcome project_id request_id target transport].freeze
+        TERMINAL_BINDING_FIELDS = %w[request_id assignment_id attempt_id project_id operation
+          input_digest target candidate_head executor_uid transport].freeze
+
+        def terminal_state?(state)
+          %w[succeeded failed failed-settled].include?(state)
+        end
+
+        def validate_terminal_receipt!(current, state, receipt)
+          unless receipt.is_a?(Hash) && receipt.keys.sort == TERMINAL_RECEIPT_FIELDS.sort
+            raise AttemptErrors::ReceiptRejected,
+              "Service terminal receipt has invalid fields"
+          end
+          TERMINAL_BINDING_FIELDS.each do |key|
+            unless receipt[key] == current[key]
+              raise AttemptErrors::ReceiptRejected, "Service terminal receipt does not match #{key}"
+            end
+          end
+          expected_outcome = (state == "failed-settled") ? "failed" : state
+          evidence_items = receipt["evidence"]
+          valid_evidence = evidence_items.is_a?(Array) && !evidence_items.empty? &&
+            evidence_items.all? do |item|
+              item.is_a?(Hash) && item.keys.sort == %w[ref sha256] &&
+                item["ref"].is_a?(String) && item["ref"].match?(/\A[a-zA-Z0-9_.:\/-]{1,256}\z/) &&
+                item["sha256"].is_a?(String) && item["sha256"].match?(/\A[0-9a-f]{64}\z/)
+            end
+          executor_valid = receipt["executor_uid"].is_a?(Integer) && receipt["executor_uid"] >= 0
+          unless receipt["outcome"] == expected_outcome && executor_valid && valid_evidence
+            raise AttemptErrors::ReceiptRejected, "Service terminal receipt has invalid executor or evidence"
+          end
+          if state == "failed-settled" &&
+              !receipt["evidence"].any? { |item| item["ref"].end_with?("no-effect") }
+            raise AttemptErrors::ReceiptRejected,
+              "Service settlement requires a no-effect attestation artifact"
+          end
+          repo_root = File.realpath(@repo_root)
+          receipt["evidence"].each do |item|
+            path = File.expand_path(item["ref"], repo_root)
+            real = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+              raise AttemptErrors::ReceiptRejected,
+                "Service terminal receipt evidence is unverifiable: #{item["ref"]}"
+            end
+            intact = begin
+              real.start_with?(repo_root + File::SEPARATOR) &&
+                Digest::SHA256.file(real).hexdigest == item["sha256"]
+            rescue Errno::EACCES, Errno::ELOOP
+              false
+            end
+            raise AttemptErrors::ReceiptRejected,
+              "Service terminal receipt evidence is unverifiable: #{item["ref"]}" unless intact
+            attestation = /^ace-service-attestation request:#{Regexp.escape(current["request_id"])} \
+input:#{Regexp.escape(current["input_digest"])} outcome:(\S+)( no-effect:(\S+))?$/
+            attested = File.read(real).scan(attestation).first
+            attested_outcome = state == "failed-settled" ? "failed" : state
+            unless attested && attested.first == attested_outcome &&
+                (state == "failed-settled" ? attested[2] == "true" : true)
+              raise AttemptErrors::ReceiptRejected,
+                "Service terminal receipt evidence does not attest #{attested_outcome}: #{item["ref"]}"
+            end
+          end
+        end
+
+        def service_request(request_id)
+          validate_request_id!(request_id)
+          value = ref_value
+          return nil unless value
+          out, stderr, status = git("show", "#{value}:#{service_request_path(request_id)}")
+          return JSON.parse(out) if status.success?
+          return nil if stderr.include?("does not exist") || stderr.include?("exists on disk")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot read service request: #{stderr}"
+        rescue JSON::ParserError
+          raise AttemptErrors::EvidenceUnavailable, "Corrupt service request #{request_id}"
+        end
+
+        # Every service request recorded in this evidence ref, whatever the
+        # owning assignment. Backs the journal-wide request-ID and
+        # authorization-consumption checks.
+        # Another live request holding the same exact authorization for the
+        # same operation, project and target. Only requests that were born
+        # rejected (never claimed, never dispatched) leave the decision
+        # unconsumed: a withdrawn or failed claim keeps it consumed until
+        # attributable evidence proves the effect did not occur.
+        def authorization_conflict(binding)
+          authorization = binding["authorization"]
+          return nil unless authorization.is_a?(String) && !authorization.empty?
+          service_request_records.find do |other|
+            next false if other["request_id"] == binding.fetch("request_id")
+            next false if other["state"] == "rejected" && other["consumed"] == false
+            # A settled failure frees the exact authorization only while its
+            # no-effect evidence remains verifiable in the repository.
+            next false if other["state"] == "failed-settled" && settlement_evidence_intact?(other)
+            other["authorization"] == authorization &&
+              other["operation"] == binding.fetch("operation") &&
+              other["project_id"] == binding.fetch("project_id") &&
+              other["target"] == binding.fetch("target")
+          end
+        end
+
+        def settlement_evidence_intact?(record)
+          receipt = record["receipt"]
+          return false unless receipt.is_a?(Hash)
+          repo_root = File.realpath(@repo_root)
+          Array(receipt["evidence"]).all? do |item|
+            path = File.expand_path(item["ref"].to_s, repo_root)
+            real = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+              next false
+            end
+            begin
+              real.start_with?(repo_root + File::SEPARATOR) &&
+                Digest::SHA256.file(real).hexdigest == item["sha256"]
+            rescue Errno::EACCES, Errno::ELOOP
+              false
+            end
+          end
+        end
+
+        def service_request_records
+          value = ref_value
+          return [] unless value
+          paths, stderr, status = git("ls-tree", "-r", "--name-only", value, "--", "execution/requests/")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot read service request index: #{stderr}" unless status.success?
+          paths.lines.map(&:strip).select { |path| path.end_with?(".json") }.filter_map do |path|
+            content, error, read_status = git("show", "#{value}:#{path}")
+            unless read_status.success?
+              raise AttemptErrors::EvidenceUnavailable, "Cannot read service request #{path}: #{error}"
+            end
+            JSON.parse(content)
+          end
+        rescue JSON::ParserError
+          raise AttemptErrors::EvidenceUnavailable, "Corrupt service request index"
+        end
+
+        def service_requests(assignment_id)
+          request_ids = read_events(assignment_id)
+            .select { |event| event["type"] == "service_claim" }
+            .map { |event| event.dig("payload", "request_id") }.compact.uniq
+          request_ids.filter_map { |request_id| service_request(request_id) }
+        end
+
         # All attempts derivable from the journal, reconstructed from intent
         # and process_start facts with journal-authoritative state. The
         # journal is the owner of attempt-state interpretation.
@@ -155,17 +370,81 @@ module Ace
           value = ref_value
           return [] if value.nil?
 
+          paths, stderr, status = git("ls-tree", "-d", "--name-only", value, "--", "execution/")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot discover journal assignments: #{stderr}" unless status.success?
+          paths.lines.map { |path| path.strip.delete_prefix("execution/") }
+            .reject { |id| id == "requests" }.sort
+        end
+
+        private
+
+        def update_service_request(request_id, expected:, replacement:, event_type:, guard: nil)
+          validate_request_id!(request_id)
           with_lock do
-            ensure_checkout!
-            sync_checkout(value)
-            Dir.glob(File.join(checkout_dir, "execution", "*"))
-              .select { |path| File.directory?(path) }
-              .map { |path| File.basename(path) }
-              .sort
+            CAS_ATTEMPTS.times do
+              old = ref_value
+              ensure_checkout!
+              old = ref_value if old.nil?
+              sync_checkout(old)
+              # Guards (for example authorization consumption) re-run inside
+              # the lock against the ref being committed, so a racing claim
+              # cannot slip through between the check and the CAS.
+              if guard
+                conflict = guard.call
+                if conflict
+                  raise AttemptErrors::Conflict,
+                    "Authorization reference already consumed by request #{conflict.fetch("request_id")}"
+                end
+              end
+              path = File.join(checkout_dir, service_request_path(request_id))
+              existing = File.exist?(path) ? JSON.parse(File.read(path)) : nil
+              if expected.nil? && existing
+                return existing if existing.except("state", "receipt", "reason", "claimed_at") ==
+                  replacement.except("state", "receipt", "reason", "claimed_at")
+                raise AttemptErrors::Conflict, "Service request #{request_id} has different input"
+              end
+              if expected && existing != expected
+                raise AttemptErrors::Conflict, "Service request #{request_id} changed during transition"
+              end
+              terminal = existing && %w[succeeded failed rejected].include?(existing["state"])
+              settlement = existing && existing["state"] == "failed" && replacement["state"] == "failed-settled"
+              if expected && existing && terminal && !settlement
+                raise AttemptErrors::InvalidState, "Service request #{request_id} is terminal"
+              end
+
+              FileUtils.mkdir_p(File.dirname(path))
+              File.write(path, JSON.pretty_generate(replacement))
+              assignment_id = replacement.fetch("assignment_id")
+              attempt_id = replacement.fetch("attempt_id")
+              prior = read_events(assignment_id).reverse
+                .find { |entry| entry["attempt_id"] == attempt_id }&.fetch("digest")
+              payload = {"request_id" => request_id, "state" => replacement.fetch("state"),
+                         "input_digest" => replacement.fetch("input_digest"),
+                         "receipt_digest" => replacement["receipt"] &&
+                           Atoms::EvidenceDigest.digest(replacement["receipt"])}
+              event = Models::EvidenceEvent.build(type: event_type, attempt_id: attempt_id,
+                payload: payload, previous_digest: prior)
+              write_event_files(assignment_id, [event])
+              git!("-C", checkout_dir, "add", "--", service_request_path(request_id),
+                "execution/#{assignment_id}/events")
+              state = replacement.fetch("state")
+              git!("-C", checkout_dir, "-c", "user.name=ace-assign", "-c", "user.email=ace-assign@localhost",
+                "commit", "-m", "evidence: service request #{request_id} #{state}")
+              commit = git!("-C", checkout_dir, "rev-parse", "HEAD").first
+              return replacement.merge("journal_commit" => commit) if update_ref_cas(commit, old)
+            end
+            raise AttemptErrors::EvidenceUnavailable, "Service request ref stayed conflicting"
           end
         end
 
-        private
+        def service_request_path(request_id)
+          "execution/requests/#{request_id}.json"
+        end
+
+        def validate_request_id!(request_id)
+          return if request_id.is_a?(String) && request_id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/)
+          raise ArgumentError, "invalid service request ID"
+        end
 
         # Latest lifecycle state implied by the events, or nil when the
         # events do not describe a full attempt (intent missing).
@@ -388,7 +667,7 @@ module Ace
         def git!(*argv)
           out, stderr, status = git(*argv)
           unless status.success?
-            raise AttemptErrors::EvidenceUnavailable, "git #{argv.join(' ')} failed: #{stderr}"
+            raise AttemptErrors::EvidenceUnavailable, "git #{argv.join(" ")} failed: #{stderr}"
           end
 
           [out, stderr, status]

data/lib/ace/assign/molecules/fork_session_launcher.rb

@@ -42,31 +42,46 @@ module Ace
           @interactive_builder = interactive_builder || Ace::LLM::Molecules::InteractiveCommandBuilder.new
         end
 
+        def initialize(config: nil, query_interface: Ace::LLM::QueryInterface, tmux_runner: nil, interactive_builder: nil,
+          lifecycle_exclusion: nil)
+          @config = config || Ace::Assign.config
+          @query_interface = query_interface
+          @tmux_runner = tmux_runner || TmuxControlSurfaceRunner.new
+          @interactive_builder = interactive_builder || Ace::LLM::Molecules::InteractiveCommandBuilder.new
+          @lifecycle_exclusion = lifecycle_exclusion
+        end
+
         def launch(assignment_id:, fork_root:, provider: nil, cli_args: nil, timeout: nil, cache_dir: nil, launch_mode: nil, callback_pane: nil)
           ensure_not_same_scoped_refork!(assignment_id: assignment_id, fork_root: fork_root)
           resolved_provider = provider || config.dig("execution", "provider") || DEFAULT_PROVIDER
           resolved_timeout = timeout || config.dig("execution", "timeout") || DEFAULT_TIMEOUT
           resolved_mode = resolve_launch_mode(launch_mode)
 
-          if resolved_mode == "tmux"
-            launch_tmux(
-              assignment_id: assignment_id,
-              fork_root: fork_root,
-              provider: resolved_provider,
-              cli_args: cli_args,
-              timeout: resolved_timeout,
-              cache_dir: cache_dir,
-              callback_pane: callback_pane
-            )
-          else
-            launch_provider_session(
-              assignment_id: assignment_id,
-              fork_root: fork_root,
-              provider: resolved_provider,
-              cli_args: cli_args,
-              timeout: resolved_timeout,
-              cache_dir: cache_dir
-            )
+          # Driver startup participates in prune exclusion: prune holds the
+          # exclusive side from final evidence reads through removal; a removed
+          # marker fails the launch closed instead of writing into a deleted
+          # assignment.
+          lifecycle_exclusion.with_shared(lifecycle_exclusion.assignment_key(assignment_id)) do
+            if resolved_mode == "tmux"
+              launch_tmux(
+                assignment_id: assignment_id,
+                fork_root: fork_root,
+                provider: resolved_provider,
+                cli_args: cli_args,
+                timeout: resolved_timeout,
+                cache_dir: cache_dir,
+                callback_pane: callback_pane
+              )
+            else
+              launch_provider_session(
+                assignment_id: assignment_id,
+                fork_root: fork_root,
+                provider: resolved_provider,
+                cli_args: cli_args,
+                timeout: resolved_timeout,
+                cache_dir: cache_dir
+              )
+            end
           end
         end
 
@@ -111,6 +126,10 @@ module Ace
 
         attr_reader :config, :query_interface, :tmux_runner, :interactive_builder
 
+        def lifecycle_exclusion
+          @lifecycle_exclusion ||= Molecules::LifecycleExclusion.new
+        end
+
         def resolve_launch_mode(explicit_mode)
           mode = explicit_mode.to_s.strip
           mode = config.dig("execution", "launch_mode").to_s.strip if mode.empty?

data/lib/ace/assign/molecules/lifecycle_exclusion.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+require "time"
+
+module Ace
+  module Assign
+    module Molecules
+      # Durable start/prune exclusion for assignment and worktree identities.
+      #
+      # Lock files live OUTSIDE every deletion target — under the shared Git
+      # common dir — so they survive removal of the assignment cache, the
+      # worktree, or a recreated lock pathname. Prune holds the exclusive
+      # side from its final evidence reads through completion of removal;
+      # every supported start path (attempt registration, fork/driver
+      # session launch, worktree provisioning) holds the shared side while
+      # registering a writer.
+      #
+      # A `removed` marker recorded by prune makes post-deletion starts fail
+      # closed instead of recreating the deleted identity: acquiring the
+      # shared side raises {AttemptErrors::Conflict} when the marker is
+      # present. Legitimate fresh provisioning (a new worktree for a task)
+      # clears the marker explicitly via `reset_removed`.
+      class LifecycleExclusion
+        # @param repo_root [String, nil] Repository used to resolve the
+        #   shared Git common dir (default: project root)
+        # @param root [String, nil] Explicit exclusion root (tests)
+        def initialize(repo_root: nil, root: nil)
+          @root = root || self.class.default_root(repo_root)
+        end
+
+        # The exclusion root shared by every writer and prune for this repo.
+        # Sandboxed environments (CACHE_BASE) scope it under the cache base,
+        # which itself is never a deletion target; otherwise it lives under
+        # the shared Git common dir, which survives worktree removal.
+        def self.default_root(_repo_root = nil)
+          cache_base = ENV["CACHE_BASE"]
+          if cache_base && !cache_base.empty?
+            return File.join(File.expand_path(cache_base), ".exclusion")
+          end
+
+          repo_root = Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
+          common_dir, _stderr, status = Open3.capture3(
+            "git", "-C", repo_root, "rev-parse", "--path-format=absolute", "--git-common-dir"
+          )
+          base = status.success? && !common_dir.to_s.strip.empty? ? common_dir.strip : File.join(repo_root, ".git")
+          File.join(base, "ace", "lifecycle-exclusion")
+        end
+
+        def assignment_key(assignment_id)
+          "assignment:#{assignment_id}"
+        end
+
+        # Task identity is the canonical worktree identity: work-on derives
+        # the worktree path from the task ref, and prune candidates carry
+        # the same task id.
+        def task_key(task_id)
+          "task:#{task_id}"
+        end
+
+        def worktree_key(worktree_path)
+          canonical = begin
+            File.realpath(worktree_path.to_s)
+          rescue Errno::ENOENT, Errno::EACCES
+            File.expand_path(worktree_path.to_s)
+          end
+          "worktree:#{canonical}"
+        end
+
+        # Hold the exclusive side while recomputing proofs and removing the
+        # target. Start paths block for the whole block.
+        #
+        # @param key [String] Identity key
+        # @yield Required block executed under exclusive exclusion
+        def with_exclusive(key)
+          raise ArgumentError, "exclusion key is required" if key.to_s.empty?
+
+          lock = open_lock(key)
+          lock.flock(File::LOCK_EX)
+          begin
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+            lock.close
+          end
+        end
+
+        # Hold the shared side while registering a writer or creating a
+        # resource. Fails closed when the identity was pruned.
+        #
+        # @param key [String] Identity key
+        # @param reset_removed [Boolean] Clear a stale removed marker instead
+        #   of raising (legitimate fresh provisioning of the same pathname)
+        def with_shared(key, reset_removed: false)
+          raise ArgumentError, "exclusion key is required" if key.to_s.empty?
+
+          lock = open_lock(key)
+          lock.flock(File::LOCK_SH)
+          begin
+            if removed?(key)
+              unless reset_removed
+                raise AttemptErrors::Conflict, removed_message(key)
+              end
+
+              clear_removed!(key)
+            end
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+            lock.close
+          end
+        end
+
+        # Hold the shared side on several identities at once (acquired in the
+        # given order, released in reverse — callers must use one consistent
+        # global order, task before assignment, to avoid deadlock). Fails
+        # closed when any identity was pruned.
+        def with_shared_multi(keys, reset_removed: false)
+          ordered = Array(keys).compact.reject { |key| key.to_s.empty? }.uniq
+          raise ArgumentError, "exclusion keys are required" if ordered.empty?
+
+          locks = ordered.map { |key| open_lock(key) }
+          begin
+            locks.each { |lock| lock.flock(File::LOCK_SH) }
+            ordered.each do |key|
+              if removed?(key)
+                unless reset_removed
+                  raise AttemptErrors::Conflict, removed_message(key)
+                end
+
+                clear_removed!(key)
+              end
+            end
+            yield
+          ensure
+            locks.reverse_each do |lock|
+              lock.flock(File::LOCK_UN)
+              lock.close
+            end
+          end
+        end
+
+        # Record that the identity was removed. Call while holding the
+        # exclusive side, BEFORE deleting the target.
+        def record_removed!(key)
+          atomic_write(
+            state_path(key),
+            JSON.generate({"removed" => true, "removed_at" => Time.now.utc.iso8601, "key" => key})
+          )
+        end
+
+        def removed?(key)
+          state = JSON.parse(File.read(state_path(key)))
+          state["removed"] == true
+        rescue Errno::ENOENT, JSON::ParserError, TypeError
+          false
+        end
+
+        def clear_removed!(key)
+          File.delete(state_path(key))
+        rescue Errno::ENOENT
+          nil
+        end
+
+        private
+
+        attr_reader :root
+
+        def open_lock(key)
+          FileUtils.mkdir_p(root)
+          File.open(lock_path(key), File::RDWR | File::CREAT)
+        end
+
+        def lock_path(key)
+          File.join(root, "#{Digest::SHA256.hexdigest(key)}.lock")
+        end
+
+        def state_path(key)
+          File.join(root, "#{Digest::SHA256.hexdigest(key)}.state.json")
+        end
+
+        def removed_message(key)
+          identity = key.to_s.sub(/\A[^:]+:/, "")
+          case key
+          when /\Aassignment:/
+            "Assignment #{identity} was pruned; refusing to start a writer on a removed identity"
+          when /\Atask:/
+            "Task #{identity} worktree was pruned; refusing to start a writer on a removed identity"
+          else
+            "Worktree #{identity} was pruned; refusing to start a writer on a removed identity"
+          end
+        end
+
+        def atomic_write(path, content)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir)
+          temp = File.join(dir, ".tmp-#{Process.pid}-#{rand(1_000_000)}")
+          File.write(temp, content)
+          File.rename(temp, path)
+        ensure
+          File.delete(temp) if temp && File.exist?(temp)
+        end
+      end
+    end
+  end
+end