ace-coworker 0.6.0

data/lib/ace/coworker/molecules/task_record_writer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Atomic writer of the durable per-assignment record inside the task's
+      # own folder (<task_path>/coworker/<assignment_id>.md). Never touches
+      # task spec files, frontmatter, or status — the record is the
+      # contract-sanctioned per-task progress location.
+      class TaskRecordWriter
+        def initialize(task_path:)
+          @task_path = task_path
+        end
+
+        def record_path(assignment_id)
+          id = validated(assignment_id)
+          File.join(@task_path, "coworker", "#{id}.md")
+        end
+
+        def write(assignment_id, content)
+          path = record_path(assignment_id)
+          FileUtils.mkdir_p(File.dirname(path))
+          tmp_path = "#{path}.tmp.#{Process.pid}"
+          File.write(tmp_path, content)
+          File.rename(tmp_path, path)
+          path
+        end
+
+        private
+
+        def validated(assignment_id)
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}'"
+          end
+
+          id
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/worktree_executor_probe.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "yaml"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Reads the executor truth of a worktree: its coworker config
+      # (resolved through the coworker config cascade anchored at the
+      # probed worktree — the same resolution an `ace-coworker` process
+      # running inside that worktree performs, so a commissioned
+      # `config_path` such as `.ace-local/coworker/worker.yml` is
+      # honored; read leniently) and the assignment inventory via
+      # `ace-assign list --all --format json` (subprocess argv contract
+      # with explicit cwd, ADR-031).
+      class WorktreeExecutorProbe
+        DEFAULT_RUNNER = ->(argv, cwd) { Open3.capture3(*argv, chdir: cwd) }
+        # Coworker config cascade files that may carry a `config_path`
+        # override for the probed worktree (project `.ace` and user tiers;
+        # the gem-defaults tier equals the loader's built-in default).
+        CASCADE_PATTERNS = ["coworker/config.yml", "coworker/config.yaml"].freeze
+
+        attr_reader :project_root
+
+        def initialize(project_root:, runner: DEFAULT_RUNNER)
+          @project_root = project_root
+          @runner = runner
+        end
+
+        # Probes one worktree. Never returns errors: an unreadable config is
+        # reported as Atoms::ActiveExecutorRule::UNPARSEABLE; operational
+        # failures (missing ace-assign CLI, failed listing, unparseable
+        # output) raise Error instead.
+        #
+        # @return [Hash] {config: Hash | nil | Atoms::ActiveExecutorRule::UNPARSEABLE,
+        #   assignments: Array<Hash{"id","name","state","progress"}>}
+        # @raise [Error] when the assignment inventory cannot be read
+        def probe(worktree_path)
+          {
+            config: read_config(worktree_path),
+            assignments: list_assignments(worktree_path)
+          }
+        end
+
+        private
+
+        def read_config(worktree_path)
+          # Deliberate read-only asymmetry (8xi16mz4): unlike
+          # CommissionOrchestrator#resolve_target, which refuses
+          # paths escaping the project root, the probe follows
+          # whatever config_path the cascade resolves — including an
+          # absolute or ../ path — because it only READS what an
+          # ace-coworker loader process inside that worktree would
+          # read anyway; there is no mutation to contain.
+          path = Molecules::ConfigLoader.new(
+            project_root: worktree_path,
+            defaults: cascade_defaults(worktree_path)
+          ).config_path
+          return nil unless File.file?(path)
+
+          begin
+            raw = YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+          rescue Psych::SyntaxError, StandardError
+            return Atoms::ActiveExecutorRule::UNPARSEABLE
+          end
+          raw.is_a?(Hash) ? raw : Atoms::ActiveExecutorRule::UNPARSEABLE
+        end
+
+        # Merge the coworker config cascade anchored at the probed
+        # worktree (project `.ace` tiers from the worktree up to its root,
+        # then the user tier) — the same file set and order
+        # ConfigResolver#resolve_file uses, restricted to the tiers that
+        # can override `config_path`. A layer that cannot contribute —
+        # YAML that is not a mapping (e.g. a list) or that fails to
+        # parse (e.g. unresolved merge-conflict markers in the
+        # worktree's own `.ace/coworker/config.yml`) — is skipped
+        # per-layer, mirroring the non-mapping case: wiping the
+        # already-merged lower tiers would silently drop a valid
+        # `config_path` override and hide a commissioned executor.
+        # A cascade that cannot even be enumerated falls back to the
+        # loader's default config location.
+        def cascade_defaults(worktree_path)
+          finder = Ace::Support::Config::Molecules::ConfigFinder.new(
+            file_patterns: CASCADE_PATTERNS, start_path: worktree_path)
+          layers = finder.find_all.select(&:exists).map(&:path)
+          merged = {}
+          layers.reverse_each do |path|
+            data = begin
+              Ace::Support::Config::Molecules::YamlLoader.load_file(path).data
+            rescue StandardError
+              next
+            end
+            merged = Ace::Support::Config::Atoms::DeepMerger.merge(merged, data) if data.is_a?(Hash)
+          end
+          merged
+        rescue StandardError
+          {}
+        end
+
+        def list_assignments(worktree_path)
+          argv = [assign_binary, "list", "--all", "--format", "json"]
+          begin
+            out, err, status = @runner.call(argv, worktree_path)
+          rescue Errno::ENOENT
+            raise Error, "required CLI '#{assign_binary}' not found; install the ace-assign gem"
+          end
+          unless status.success?
+            message = err.to_s.strip.empty? ? out.to_s.strip : err.to_s.strip
+            raise Error, "cannot list assignments in '#{worktree_path}': #{message}"
+          end
+
+          begin
+            payload = JSON.parse(out)
+          rescue JSON::ParserError => e
+            raise Error, "cannot parse ace-assign list for '#{worktree_path}': #{e.message}"
+          end
+          return [] unless payload.is_a?(Array)
+
+          payload.filter_map do |entry|
+            next unless entry.is_a?(Hash)
+
+            {"id" => entry["id"].to_s, "name" => entry["name"].to_s,
+             "state" => entry["state"].to_s, "progress" => entry["progress"].to_s}
+          end
+        end
+
+        # Prefer the repo binstub when present (agent shells do not activate
+        # mise, so bare ace-* may resolve to stale installed gems); the
+        # subprocess still runs with cwd = the probed worktree.
+        def assign_binary
+          binstub = File.join(@project_root, "bin", "ace-assign")
+          File.executable?(binstub) ? binstub : "ace-assign"
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/worktree_provision_probe.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "ace/git/worktree"
+require_relative "../atoms/prepare_decision"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Wraps the worktree owner (ace-git-worktree) for the preparation
+      # decision procedure: association-aware find (switch), idempotent
+      # create, and stale-metadata recovery (prune + recreate, mirroring
+      # the proven ace-overseer provisioner pattern). Returns structured
+      # disposition hashes; never raises for expected outcomes.
+      class WorktreeProvisionProbe
+        def initialize(project_root:, manager: nil)
+          @project_root = project_root
+          @manager = manager || Ace::Git::Worktree::Organisms::WorktreeManager.new(project_root: project_root)
+        end
+
+        # Runs the find/prepare/recover flow for one task.
+        #
+        # @return [Hash] {disposition:, reason:, worktree_path:, branch:}
+        #   disposition: :created | :recovered | :reuse | :conflict_mismatch |
+        #   :error | :would_create | :would_recover
+        def ensure_prepared(task_ref:, expected_task_id:, dry_run: false)
+          decision = locate(task_ref: task_ref, expected_task_id: expected_task_id)
+
+          case decision[:disposition]
+          when :reuse, :conflict_mismatch
+            decision
+          when :stale_recovery
+            recover_stale(task_ref: task_ref, decision: decision, dry_run: dry_run)
+          when :miss
+            prepare(task_ref: task_ref, dry_run: dry_run)
+          end
+        end
+
+        # Read-only find: association-aware switch plus stale detection.
+        # The owner's switch never resolves a worktree whose directory is
+        # missing (it fails instead), so a failed switch is cross-checked
+        # against the association inventory: a registration for this task
+        # pointing at a missing directory is stale metadata, not a miss.
+        def locate(task_ref:, expected_task_id:)
+          switch = @manager.switch(task_ref.to_s)
+          stale = stale_registration(expected_task_id) unless switch[:success]
+          Atoms::PrepareDecision.from_switch(switch,
+            expected_task_id: expected_task_id, stale_registration: stale)
+        end
+
+        private
+
+        def stale_registration(expected_task_id)
+          listing = @manager.list_all
+          return nil unless listing[:success]
+
+          expected = Atoms::PrepareDecision.expected_ids(expected_task_id)
+          stale = listing[:worktrees].find do |info|
+            info.respond_to?(:task_id) && expected.include?(info.task_id.to_s) &&
+              !path_exists?(info.path)
+          end
+          return nil unless stale
+
+          {task_id: stale.task_id.to_s, worktree_path: stale.path, branch: stale.branch}
+        end
+
+        def prepare(task_ref:, dry_run:)
+          return {disposition: :would_create, reason: "no worktree for this task yet",
+                  worktree_path: nil, branch: nil} if dry_run
+
+          create = @manager.create_task(task_ref.to_s)
+          return create_with_verification(task_ref: task_ref, create: create) if create[:success]
+
+          occupied = expected_directory_exists?(task_ref)
+          Atoms::PrepareDecision.from_create(create, occupied_directory: occupied)
+        end
+
+        def recover_stale(task_ref:, decision:, dry_run:)
+          return decision.merge(disposition: :would_recover) if dry_run
+
+          prune = @manager.prune
+          unless prune[:success]
+            return {disposition: :error,
+                    reason: "#{prune[:error]} (could not prune stale worktree metadata at " \
+                            "#{decision[:worktree_path]} before recreation)",
+                    worktree_path: decision[:worktree_path], branch: nil}
+          end
+
+          retry_create = @manager.create_task(task_ref.to_s)
+          if retry_create[:success]
+            return Atoms::PrepareDecision.from_create(retry_create.merge(recovered: true))
+          end
+
+          # Same occupied-location rule as the miss path: a foreign
+          # occupant of the expected directory is a conflict, never an
+          # operational error.
+          occupied = path_exists?(decision[:worktree_path])
+          mismatch = Atoms::PrepareDecision.from_create(retry_create, occupied_directory: occupied)
+          return mismatch if mismatch[:disposition] == :conflict_mismatch
+
+          # The stale worktree's branch survives its directory (committed
+          # work lives on it): when recreation trips over the surviving
+          # branch, reattach a worktree to it instead of minting a fresh
+          # branch that would orphan that work.
+          reattached = @manager.create(decision[:branch].to_s, path: decision[:worktree_path])
+          return Atoms::PrepareDecision.from_create(reattached.merge(recovered: true)) if reattached[:success]
+
+          {disposition: :error,
+           reason: "#{retry_create[:error]} (stale worktree metadata at " \
+                   "#{decision[:worktree_path]} was already pruned and branch reattach " \
+                   "failed too; retry the prepare command)",
+           worktree_path: decision[:worktree_path], branch: nil}
+        end
+
+        def create_with_verification(task_ref:, create:)
+          decision = Atoms::PrepareDecision.from_create(create)
+          return decision if %i[conflict_mismatch error].include?(decision[:disposition])
+          return decision if path_exists?(create[:worktree_path])
+
+          recover_stale(task_ref: task_ref,
+            decision: {worktree_path: create[:worktree_path], branch: create[:branch]},
+            dry_run: false)
+        end
+
+        def expected_directory_exists?(task_ref)
+          preview = @manager.create_task(task_ref.to_s, {dry_run: true})
+          path = preview.dig(:would_create, :worktree_path) if preview[:success]
+          path && path_exists?(path)
+        end
+
+        def path_exists?(worktree_path)
+          path = worktree_path.to_s
+          !path.empty? && File.directory?(path)
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/organisms/commission_orchestrator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Ace
+  module Coworker
+    module Organisms
+      # Orchestrates `ace-coworker commission`: expand a role preset plus the
+      # commission identity (task, assignment, overseer) into the documented
+      # .ace-local/coworker/config.yml. A single-role writer primitive for
+      # the location ace-coworker already owns: no sequencing, no
+      # active-driver detection, no role policies (those belong to the
+      # planner, L4.2/L4.3).
+      class CommissionOrchestrator
+        Commission = Struct.new(
+          :role, :task, :assignment, :overseer, :config_path, :config,
+          :preset_source, :dry_run, :written,
+          keyword_init: true
+        ) do
+            def to_h
+              {
+                "role" => role,
+                "task" => task,
+                "assignment" => assignment,
+                "overseer" => overseer,
+                "config_path" => config_path,
+                "config" => config,
+                "preset_source" => preset_source,
+                "dry_run" => dry_run,
+                "written" => written
+              }
+            end
+          end
+
+        # @param project_root [String] absolute project root
+        # @param preset_loader [Molecules::RolePresetLoader]
+        # @param task_probe [Molecules::TaskProbe]
+        # @param assignment_metadata [Molecules::AssignmentMetadata]
+        # @param config_path [String, nil] explicit target (absolute or
+        #   root-relative); default from the config cascade
+        def initialize(project_root:, preset_loader:, task_probe:, assignment_metadata:,
+          config_path: nil, config_loader: nil)
+          @project_root = project_root
+          @preset_loader = preset_loader
+          @task_probe = task_probe
+          @assignment_metadata = assignment_metadata
+          @config_loader = config_loader ||
+            Molecules::ConfigLoader.new(project_root: project_root, defaults: Ace::Coworker.config)
+          @config_path = config_path
+        end
+
+        # @return [Commission]
+        # @raise [Error] on unknown role, identity mismatch, invalid
+        #   assembly, a refused overwrite, a config path escaping the
+        #   project root, or a directory config target
+        def call(role:, task:, assignment:, overseer:, start_prompt: nil, force: false, dry_run: false)
+          preset = @preset_loader.fetch(role)
+
+          # Canonicalize the task identity first: the assignment match and
+          # the written config use the resolved full id, so a short ref
+          # (e.g. "ccc") commissioning the recorded task (8xh.t.ccc) is
+          # accepted while a genuinely foreign task stays rejected.
+          resolved = @task_probe.resolve(task)
+          raise Error, "task '#{task}' not found in this worktree" if resolved.nil?
+
+          canonical_task = resolved.id.to_s
+          @assignment_metadata.verify_task_match!(assignment, canonical_task)
+
+          prompt = start_prompt.to_s.strip.empty? ? render_prompt(preset, role, canonical_task, assignment, overseer) : start_prompt
+
+          config = build_config(preset, role: role, task: canonical_task, assignment: assignment,
+            overseer: overseer, prompt: prompt)
+          errors = Atoms::ConfigSchema.errors(config)
+          unless errors.empty?
+            raise Error, "commissioned config is invalid: #{errors.join('; ')}"
+          end
+
+          target = resolve_target
+          write_config(target, config, force: force) unless dry_run
+
+          Commission.new(
+            role: role, task: canonical_task, assignment: assignment, overseer: overseer,
+            config_path: relativize(target), config: config,
+            preset_source: preset["source"], dry_run: dry_run,
+            written: dry_run ? false : true
+          )
+        end
+
+        private
+
+        def render_prompt(preset, role, task, assignment, overseer)
+          Atoms::PromptTemplate.render(preset["start_prompt"],
+            {"task" => task, "assignment" => assignment, "role" => role, "overseer" => overseer})
+        end
+
+        def build_config(preset, role:, task:, assignment:, overseer:, prompt:)
+          config = {
+            "role" => role,
+            "instructions" => preset["instructions"],
+            "start_prompt" => prompt,
+            "task" => task,
+            "assignment" => assignment,
+            "overseer" => overseer
+          }
+          config["reporting"] = {"channel" => preset["reporting"]} unless preset["reporting"].to_s.empty?
+          config["errors"] = {"on_failure" => preset["errors"]} unless preset["errors"].to_s.empty?
+          config
+        end
+
+        def resolve_target
+          target = @config_path ? File.expand_path(@config_path, @project_root) : @config_loader.config_path
+          unless target.start_with?("#{@project_root}/")
+            raise Error, "config path '#{relativize(target)}' escapes the project root"
+          end
+
+          target
+        end
+
+        def write_config(target, config, force:)
+          if File.directory?(target)
+            raise Error, "config path '#{relativize(target)}' is a directory; --config must name a file"
+          end
+
+          # The exist? -> mv sequence below has a TOCTOU window on the
+          # overwrite refusal: commission is a single-planner local write
+          # primitive, so concurrent writers on the same config are out of
+          # scope by design; this check is a guard, not a hard guarantee.
+          if File.exist?(target) && !force
+            raise Error, "refusing to overwrite '#{relativize(target)}'; use --force"
+          end
+
+          FileUtils.mkdir_p(File.dirname(target))
+          content = YAML.safe_dump(config)
+          Dir.mktmpdir(".commission", File.dirname(target)) do |tmp|
+            temp = File.join(tmp, "config.yml")
+            File.write(temp, content)
+            FileUtils.mv(temp, target)
+          end
+        end
+
+        def relativize(path)
+          path.start_with?(@project_root) ? path.delete_prefix("#{@project_root}/") : path
+        end
+      end
+    end
+  end
+end