ace-coworker 0.6.0

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

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/project_root"
+require_relative "../molecules/task_probe"
+require_relative "../molecules/config_loader"
+require_relative "../molecules/worktree_provision_probe"
+require_relative "../molecules/worktree_executor_probe"
+require_relative "../molecules/role_sequence_composer"
+require_relative "../molecules/hitl_reporter"
+require_relative "../atoms/active_executor_rule"
+
+module Ace
+  module Coworker
+    module Organisms
+      # Orchestrates `ace-coworker prepare`: the planner accepts a
+      # preparation commission (task + expected role sequence), finds or
+      # prepares exactly one proper worktree for that task, and composes
+      # the role-sequence assignments for the WHOLE sequence in one go
+      # (L4.2), so roles hand off sequentially after start without the
+      # overseer re-commissioning preparation per step. Re-preparation
+      # reuses the existing worktree and the already-composed assignments
+      # with zero redundant writes; an active executor or a mismatched
+      # worktree escalates to the overseer via ace-hitl instead of
+      # overwriting work. dry_run: performs the full resolution and
+      # conflict detection with zero effects (assignments are planned,
+      # not written, because the worktree does not exist yet). After a successful preparation the
+      # planner sends a READINESS report to the overseer via ace-hitl
+      # (L4.4: what was prepared — worktree, assignments, start configs
+      # — plus the exact first step; a report expects no reply); role
+      # errors and a missing overseer address are GAPS that never pass
+      # as ready and reach the overseer through the same conflict
+      # escalation path (question = a decision is needed). dry_run
+      # sends nothing.
+      class PrepareOrchestrator
+        DISPOSITIONS = {
+          created: "created", recovered: "recovered", reuse: "reused",
+          would_create: "would_create", would_recover: "would_recover"
+        }.freeze
+
+        def initialize(project_root: nil, task_probe: nil, provision_probe: nil,
+          executor_probe: nil, hitl_reporter: nil, config_loader: nil, config: nil,
+          sequence_composer: nil, start_config_writer: nil)
+          @config = config || Ace::Coworker.config
+          @project_root = project_root || Molecules::ProjectRoot.new.resolve
+          @task_probe = task_probe || Molecules::TaskProbe.new(project_root: @project_root)
+          @provision_probe = provision_probe || Molecules::WorktreeProvisionProbe.new(project_root: @project_root)
+          @executor_probe = executor_probe || Molecules::WorktreeExecutorProbe.new(project_root: @project_root)
+          @hitl_reporter = hitl_reporter || Molecules::HitlReporter.new(project_root: @project_root)
+          @config_loader = config_loader ||
+            Molecules::ConfigLoader.new(project_root: @project_root, defaults: @config)
+          @sequence_composer = sequence_composer
+          @start_config_writer = start_config_writer
+        end
+
+        # @param task_ref [String] task reference
+        # @param roles [Array<String>] expected role sequence (already
+        #   normalized: non-blank, deduplicated, order preserved)
+        # @param to [String, nil] escalation recipient override
+        # @param config_path [String, nil] explicit planner config path
+        # @param dry_run [Boolean] suppress all effects
+        # @return [Models::Preparation]
+        # @raise [Error] for an unresolvable task or an operational failure
+        def call(task_ref:, roles:, to: nil, config_path: nil, dry_run: false)
+          task = @task_probe.resolve(task_ref)
+          raise Error, "task '#{task_ref}' not found in this worktree" if task.nil?
+
+          task_path = task.respond_to?(:path) && task.path ? task.path : task.id.to_s
+          task_id = task.id.to_s
+
+          decision = @provision_probe.ensure_prepared(
+            task_ref: task_ref, expected_task_id: task_id, dry_run: dry_run)
+          return conflict_result(task: task_id, task_path: task_path, roles: roles,
+            kind: "mismatched_worktree", detail: decision[:reason],
+            worktree_path: decision[:worktree_path], to: to,
+            config_path: config_path, dry_run: dry_run) if decision[:disposition] == :conflict_mismatch
+          if decision[:disposition] == :error
+            raise Error, "cannot prepare worktree for task '#{task_ref}': #{decision[:reason]}"
+          end
+
+          disposition = DISPOSITIONS.fetch(decision[:disposition])
+          return success(task: task_id, task_path: task_path, roles: roles,
+            disposition: disposition, worktree_path: decision[:worktree_path],
+            branch: decision[:branch], assignments: [], dry_run: dry_run) if would_disposition?(disposition)
+
+          executor = @executor_probe.probe(decision[:worktree_path])
+          rule = Atoms::ActiveExecutorRule.evaluate(
+            config: executor[:config], assignments: executor[:assignments])
+          if rule[:active]
+            return conflict_result(task: task_id, task_path: task_path, roles: roles,
+              kind: "active_executor", detail: active_detail(rule),
+              worktree_path: decision[:worktree_path], to: to,
+              config_path: config_path, dry_run: dry_run,
+              assignments: executor[:assignments], active_executor: rule[:evidence])
+          end
+
+          # Role errors are GAPS (L4.4): a sequence that cannot be
+          # composed is never reported as ready; the worktree stays
+          # prepared and the gap escalates to the overseer (question —
+          # a decision is needed), never a silent bare error.
+          sequence = begin
+            compose_sequence(task_id, roles, decision[:worktree_path], dry_run)
+          rescue Error => e
+            return conflict_result(task: task_id, task_path: task_path, roles: roles,
+              kind: "role_sequence", detail: e.message,
+              worktree_path: decision[:worktree_path], to: to,
+              config_path: config_path, dry_run: dry_run)
+          end
+
+          # Missing instruction context is a GAP too (never-ready-on-
+          # missing-context): the sequence composes, but a leg whose
+          # instruction source does not resolve would hand the executor a
+          # start command that fails immediately — reported with the
+          # concrete reason, never as a ready order.
+          gaps = instruction_gaps(sequence, decision[:worktree_path])
+          unless gaps.empty?
+            return conflict_result(task: task_id, task_path: task_path, roles: roles,
+              kind: "role_instructions",
+              detail: instruction_gap_detail(worktree_path: decision[:worktree_path],
+                branch: decision[:branch], disposition: disposition, gaps: gaps),
+              worktree_path: decision[:worktree_path], to: to,
+              config_path: config_path, dry_run: dry_run)
+          end
+
+          # A missing overseer address is a GAP too (L4.4): the worktree
+          # and the assignments ARE composed, but no start config is
+          # written and the commission is NOT ready — reported with the
+          # concrete reason, never as a ready order. (The lenient
+          # config-load note, if any, is appended once by conflict_result.)
+          leg_overseer, = escalation_recipient(to: to, config_path: config_path)
+          if leg_overseer.to_s.strip.empty?
+            return conflict_result(task: task_id, task_path: task_path, roles: roles,
+              kind: "missing_overseer",
+              detail: missing_overseer_detail(worktree_path: decision[:worktree_path],
+                branch: decision[:branch], disposition: disposition,
+                sequence: sequence),
+              worktree_path: decision[:worktree_path], to: to,
+              config_path: config_path, dry_run: dry_run)
+          end
+
+          start_configs = write_start_configs(task: task_id, sequence: sequence,
+            worktree_path: decision[:worktree_path], overseer: leg_overseer,
+            dry_run: dry_run)
+          report = dry_run ? nil : readiness_report(task: task_id, to: leg_overseer,
+            worktree_path: decision[:worktree_path], branch: decision[:branch],
+            disposition: disposition, assignments: sequence, start_configs: start_configs)
+          success(task: task_id, task_path: task_path, roles: roles,
+            disposition: disposition, worktree_path: decision[:worktree_path],
+            branch: decision[:branch], assignments: sequence,
+            start_configs: start_configs,
+            worktree_assignments: executor[:assignments],
+            report: report, dry_run: dry_run)
+        end
+
+        private
+
+        # Composes the whole role sequence in one go via ace-assign's plan
+        # storage in the prepared worktree. A missing role process is
+        # reported (Error) — never substituted with another role's.
+        # dry_run resolves the same sequence with zero writes (planned
+        # legs carry no assignment id).
+        def compose_sequence(task_id, roles, worktree_path, dry_run)
+          composer = @sequence_composer || Molecules::RoleSequenceComposer.new(project_root: worktree_path)
+          composer.call(task: task_id, roles: roles, dry_run: dry_run)
+        end
+
+        # Never-ready-on-missing-context (L4.4 / 8xg.t.sbz.3.2-.3.3): the
+        # instruction source of EVERY leg must resolve through the existing
+        # loader/resolver in the prepared worktree before readiness is
+        # declared — a start command that fails immediately is a gap,
+        # never a ready commission. File-path sources resolve in-process;
+        # protocol URIs (wfi://, prompt://, tmpl://) resolve through the
+        # SAME ace-nav resolver start uses, in the prepared execution
+        # context. A resolver that runs and fails is a gap; a missing
+        # ace-nav CLI (NavUnavailableError) stays a non-blocking unknown,
+        # consistent with lab verify's posture toward an absent checker.
+        # Unknown roles surface as the role_sequence gap during
+        # composition and are skipped here. Read-only: this check itself
+        # never writes.
+        def instruction_gaps(sequence, worktree_path)
+          loader = Molecules::RolePresetLoader.new(project_root: worktree_path)
+          resolver = Molecules::InstructionResolver.new(project_root: worktree_path)
+          gaps = []
+          sequence.each do |entry|
+            preset = begin
+              loader.fetch(entry["role"])
+            rescue Error
+              nil
+            end
+            next if preset.nil?
+
+            begin
+              resolver.resolve!(preset["instructions"].to_s)
+            rescue Molecules::InstructionResolver::NavUnavailableError
+              # No resolver to ask: unknown, not failed.
+              next
+            rescue Error => e
+              gaps << "role '#{entry['role']}': #{e.message}"
+            end
+          end
+          gaps
+        end
+
+        def instruction_gap_detail(worktree_path:, branch:, disposition:, gaps:)
+          detail = +"instruction source(s) do not resolve in the worktree; " \
+            "the commission is NOT ready - no leg config is written"
+          gaps.each { |gap| detail << "\n#{gap}" }
+          detail << "\nprepared: worktree #{worktree_path} (branch #{branch}, #{disposition})"
+          detail << "\ndecision needed: provide the missing instruction context " \
+            "(or a role preset pointing at an existing source) and re-run " \
+            "prepare (idempotent)"
+          detail
+        end
+
+        # The readiness report body (L4.4): what was prepared — worktree,
+        # per-role assignments, per-leg start configs — plus the exact
+        # first step, so the overseer runs the first leg without
+        # composing any ace-assign detail itself. A REPORT (no reply
+        # expected); delivery is attempted but a delivery failure never
+        # undoes the preparation — the event id stays in the result for
+        # an `ace-hitl send` retry.
+        def readiness_report(task:, to:, worktree_path:, branch:, disposition:,
+          assignments:, start_configs:)
+          event = @hitl_reporter.create_report(
+            title: "Preparation ready - #{task}/#{worktree_dir(worktree_path)}",
+            body_lines: readiness_lines(worktree_path: worktree_path, branch: branch,
+              disposition: disposition, assignments: assignments,
+              start_configs: start_configs),
+            task: task, result: "success", to: to)
+          if event.is_a?(Molecules::HitlReporter::Failure)
+            return {"kind" => "readiness", "error" => event.message}
+          end
+
+          {"kind" => "readiness", "event" => event,
+           "delivered" => @hitl_reporter.send_report(event) == true}
+        rescue Error => e
+          {"kind" => "readiness", "error" => e.message}
+        end
+
+        def readiness_lines(worktree_path:, branch:, disposition:, assignments:, start_configs:)
+          lines = ["worktree: #{worktree_path} (branch #{branch}, #{disposition})"]
+          assignments.each do |entry|
+            lines << "sequence #{entry['position']}/#{entry['of']} #{entry['role']}: " \
+              "#{entry['assignment']} (#{entry['disposition']}, #{entry['steps']} steps)"
+          end
+          start_configs.each do |entry|
+            lines << "start config #{entry['role']}: #{entry['path']} (#{entry['disposition']})"
+          end
+          first = start_configs.first
+          if first
+            lines << "first leg: ace-coworker start --config #{first['path']} in the worktree"
+          end
+          lines
+        end
+
+        def missing_overseer_detail(worktree_path:, branch:, disposition:, sequence:)
+          detail = +"no overseer address for the start configs (--to or coworker config); " \
+            "the commission is NOT ready - no leg config is written"
+          detail << "\nprepared: worktree #{worktree_path} (branch #{branch}, #{disposition})"
+          sequence.each do |entry|
+            detail << "\nprepared: assignment #{entry['role']} -> #{entry['assignment']} " \
+              "(#{entry['disposition']})"
+          end
+          detail << "\ndecision needed: supply the overseer address and re-run prepare " \
+            "with --to <address> to write the leg configs (idempotent)"
+          detail
+        end
+
+        # Writes one start config per sequence leg into the prepared
+        # worktree (.ace-local/coworker/prepare/<role>.yml) via the
+        # commission primitive; dry-run resolves them without writes.
+        def write_start_configs(task:, sequence:, worktree_path:, overseer:, dry_run:)
+          writer = @start_config_writer || Organisms::StartConfigWriter.new(worktree_path: worktree_path)
+          writer.call(task: task, sequence: sequence, overseer: overseer, dry_run: dry_run)
+        end
+
+        def would_disposition?(disposition)
+          %w[would_create would_recover].include?(disposition)
+        end
+
+        def active_detail(rule)
+          evidence = rule[:evidence]
+          if evidence["source"] == "config"
+            "a commissioned executor holds the worktree: assignment #{evidence['assignment']} " \
+              "(state #{evidence['state']})"
+          else
+            "an uncommissioned assignment is in flight: #{evidence['assignment']} " \
+              "(state #{evidence['state']})"
+          end
+        end
+
+        def conflict_result(task:, task_path:, roles:, kind:, detail:, worktree_path:,
+          to:, config_path:, dry_run:, assignments: [], active_executor: nil)
+          hitl_event = nil
+          delivered = nil
+          recipient, recipient_note = escalation_recipient(to: to, config_path: config_path)
+          detail = detail.dup
+
+          unless dry_run
+            if recipient.to_s.strip.empty?
+              detail << "\ncannot report conflict: no overseer address (--to or coworker config)"
+              detail << "\n#{recipient_note}" if recipient_note
+            else
+              begin
+                result = @hitl_reporter.create_conflict(
+                  title: "Preparation conflict - #{task}/#{worktree_dir(worktree_path)}",
+                  question_lines: conflict_question(kind: kind, detail: detail, worktree_path: worktree_path),
+                  task: task, to: recipient)
+                if result.is_a?(Molecules::HitlReporter::Failure)
+                  detail << "\ncannot report conflict: #{result.message}"
+                else
+                  hitl_event = result
+                  delivered = @hitl_reporter.send_report(hitl_event) == true
+                end
+              rescue Error => e
+                # e.g. the ace-hitl binary is missing: keep the structured
+                # conflict visible instead of replacing it with a bare error.
+                detail << "\ncannot report conflict: #{e.message}"
+              end
+            end
+          end
+
+          Models::Preparation.new(task: task, task_path: task_path, roles: roles,
+            worktree: nil, worktree_assignments: assignments,
+            active_executor: active_executor,
+            conflict: {"kind" => kind, "detail" => detail,
+                       "hitl_event" => hitl_event, "delivered" => delivered},
+            dry_run: dry_run)
+        end
+
+        def conflict_question(kind:, detail:, worktree_path:)
+          [
+            "kind: #{kind}",
+            detail,
+            "worktree preserved at #{worktree_path} - decide whether to resume, " \
+              "reassign, or remove it before re-preparing"
+          ]
+        end
+
+        # Resolves the escalation recipient: the --to override, else the
+        # coworker config's overseer. A config that fails full validation is
+        # still consulted leniently (field-only read, mirroring
+        # WorktreeExecutorProbe#read_config) so a partial planner-side config
+        # can name its overseer; a config that supplies no overseer anywhere
+        # yields a nil address plus the load error for the conflict detail
+        # instead of a silent "no address".
+        #
+        # @return [Array<String, String, nil>] recipient address and an
+        #   optional diagnostic note
+        def escalation_recipient(to:, config_path:)
+          return [to, nil] unless to.to_s.strip.empty?
+
+          cfg = @config_loader.load(path: config_path)
+          [cfg&.overseer, nil]
+        rescue Error => e
+          overseer = @config_loader.overseer(path: config_path).to_s
+          overseer.empty? ? [nil, "coworker config load failed: #{e.message}"] : [overseer, nil]
+        end
+
+        def worktree_dir(worktree_path)
+          worktree_path ? File.basename(worktree_path) : "?"
+        end
+
+        def success(task:, task_path:, roles:, disposition:, worktree_path:,
+          branch:, assignments: [], start_configs: [], worktree_assignments: [],
+          report: nil, dry_run:)
+          Models::Preparation.new(task: task, task_path: task_path, roles: roles,
+            worktree: {"path" => worktree_path, "branch" => branch, "disposition" => disposition},
+            worktree_assignments: worktree_assignments, assignments: assignments,
+            start_configs: start_configs, report: report, dry_run: dry_run)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "time"
+require "pathname"
+
+require_relative "../molecules/config_loader"
+require_relative "../molecules/task_probe"
+require_relative "../molecules/assignment_metadata"
+require_relative "../molecules/assignment_probe"
+require_relative "../molecules/step_evidence_reader"
+require_relative "../molecules/hitl_reporter"
+require_relative "../molecules/task_record_writer"
+require_relative "../molecules/report_state_store"
+require_relative "../atoms/outcome_planner"
+require_relative "../atoms/report_record_formatter"
+
+module Ace
+  module Coworker
+    module Organisms
+      # Orchestrates `ace-coworker report`: derive the outcome (ace-assign
+      # is the only truth), write the durable record into the task folder
+      # FIRST, keep helper state under .ace-local/coworker/, then report
+      # through the ace-hitl CLI. Outcome and delivery are strictly
+      # separated: a completed assignment with an undelivered report keeps
+      # the work success plus an explicit delivery error; an execution
+      # error records its cause and the unfinished step — never a false
+      # work done.
+      class ReportOrchestrator
+        ReportResult = Struct.new(:outcome, :record_path, :event_id, :delivery, :message,
+          :exit_code, :created_event, keyword_init: true)
+
+        def initialize(project_root: nil, config_loader: nil, task_probe: nil,
+          assignment_probe: nil, evidence_reader: nil, reporter: nil,
+          record_writer: nil, state_store: nil, config: nil)
+          @config = config || Ace::Coworker.config
+          @project_root = project_root || Molecules::ProjectRoot.new.resolve
+          @config_loader = config_loader || Molecules::ConfigLoader.new(project_root: @project_root, defaults: @config)
+          @task_probe = task_probe || Molecules::TaskProbe.new(project_root: @project_root)
+          @assignment_probe = assignment_probe || Molecules::AssignmentProbe.new(project_root: @project_root)
+          @evidence_reader = evidence_reader || Molecules::StepEvidenceReader.new(project_root: @project_root)
+          @reporter = reporter || Molecules::HitlReporter.new(project_root: @project_root)
+          @record_writer_factory = record_writer
+          @state_store_factory = state_store
+        end
+
+        # @param config_path [String, nil]
+        # @param assignment [String, nil] override (default: config assignment)
+        # @param result [String, nil] explicit --result
+        # @param message [String, nil] explicit cause
+        # @param step [String, nil] explicit --step
+        # @param no_send [Boolean]
+        # @param dry_run [Boolean]
+        # @return [ReportResult]
+        def call(config_path: nil, assignment: nil, result: nil, message: nil,
+          step: nil, no_send: false, dry_run: false)
+          cfg = @config_loader.load(path: config_path)
+          assignment_id = assignment.to_s.strip.empty? ? cfg.assignment : assignment.to_s.strip
+          # The selected assignment (CLI override or config) is the single
+          # identity threaded through record, evidence, and HITL message.
+          cfg = cfg.with(assignment: assignment_id)
+          @task_probe.resolve!(cfg.task)
+          @assignment_metadata ||= Molecules::AssignmentMetadata.new(project_root: @project_root)
+          @assignment_metadata.verify_task_match!(assignment_id, cfg.task)
+          snapshot = @assignment_probe.snapshot(assignment_id)
+
+          step_evidence = @evidence_reader.read(assignment_id, failed_step_number(snapshot))
+          outcome = Atoms::OutcomePlanner.plan(snapshot,
+            explicit_result: result, message: message,
+            step_evidence: step_evidence, step_override: step)
+
+          task_path = @task_probe.resolve!(cfg.task)
+          record_writer = @record_writer_factory || Molecules::TaskRecordWriter.new(task_path: task_path)
+          state_store = @state_store_factory || Molecules::ReportStateStore.new(project_root: @project_root)
+
+          return dry_run_result(outcome, cfg) if dry_run
+
+          relative_record = placeholder_record_path(cfg, assignment_id, task_path)
+          record_path = record_writer.write(assignment_id,
+            Atoms::ReportRecordFormatter.format(outcome, cfg, record_path: relative_record))
+
+          # Rerun rules: same result with an existing event => send-only
+          # redelivery (retrying delivery never retries the assignment).
+          state = state_store.read(assignment_id) || {}
+          event_id = nil
+          created_event = false
+          if !report_via_hitl?(cfg, outcome)
+            # errors.on_failure=stop: never touch HITL, not even a resend.
+          elsif state["result"] == outcome.result && state["event_id"] && @reporter.event_exists?(state["event_id"])
+            event_id = state["event_id"]
+          elsif report_via_hitl?(cfg, outcome)
+            event_id = @reporter.create(outcome, cfg)
+            if event_id.is_a?(Molecules::HitlReporter::Failure)
+              return failure_result(outcome, cfg, record_path, nil,
+                "outcome recorded: #{outcome.result} at #{record_path}; HITL create failed: #{event_id.message}")
+            end
+            created_event = true
+            # Bind the event in helper state BEFORE the send effect: an
+            # interrupt/crash during send must not orphan a possibly
+            # delivered message; a rerun reuses this ID instead of
+            # creating a duplicate.
+            state_store.write(assignment_id, {
+              "result" => outcome.result, "event_id" => event_id,
+              "record" => record_path, "delivery" => nil,
+              "updated_at" => Time.now.utc.iso8601
+            })
+          end
+
+          delivery = nil
+          if event_id && !no_send
+            send_result = @reporter.send_report(event_id)
+            if send_result == true
+              delivery = "delivered (event #{event_id})"
+            else
+              record_writer.write(assignment_id,
+                Atoms::ReportRecordFormatter.format(outcome, cfg,
+                  event_id: event_id, delivery: "failed: #{send_result.message}",
+                  record_path: relative_record))
+              return failure_result(outcome, cfg, record_path, event_id,
+                "outcome recorded: #{outcome.result} at #{record_path}; delivery failed: #{send_result.message}")
+            end
+          end
+
+          state_store.write(assignment_id, {
+            "result" => outcome.result, "event_id" => event_id,
+            "record" => record_path, "delivery" => delivery,
+            "updated_at" => Time.now.utc.iso8601
+          })
+          rewrite_record_with_delivery(record_writer, assignment_id, outcome, cfg, event_id, delivery, relative_record)
+
+          finish_result(outcome, cfg, record_path, event_id, delivery, created_event)
+        end
+
+        private
+
+        def report_via_hitl?(cfg, outcome)
+          return true if outcome.success?
+
+          # errors.on_failure=stop: record locally, skip HITL entirely.
+          cfg.on_failure != "stop"
+        end
+
+        def failed_step_number(snapshot)
+          failed = snapshot.steps.reverse.find { |s| s.status == "failed" } ||
+            snapshot.steps.find { |s| s.status == "active" } ||
+            snapshot.steps.find { |s| s.status == "pending" }
+          failed&.number
+        end
+
+        # The record evidence line must point at the REAL file: derive it
+        # from the resolved task path relative to the project root (task
+        # folders are <ref>-<slug>, never the bare ref).
+        def placeholder_record_path(cfg, assignment_id, task_path = nil)
+          task_path ||= @task_probe.resolve!(cfg.task)
+          relative = Pathname.new(task_path).relative_path_from(Pathname.new(@project_root)).to_s
+          File.join(relative, "coworker", "#{assignment_id}.md")
+        end
+
+        def rewrite_record_with_delivery(record_writer, assignment_id, outcome, cfg, event_id, delivery, relative_record)
+          record_writer.write(assignment_id,
+            Atoms::ReportRecordFormatter.format(outcome, cfg,
+              event_id: event_id, delivery: delivery || "not attempted",
+              record_path: relative_record))
+        end
+
+        def dry_run_result(outcome, cfg)
+          ReportResult.new(outcome: outcome, record_path: nil, event_id: nil,
+            delivery: nil, created_event: false,
+            message: "dry-run: outcome #{outcome.result} (nothing written)", exit_code: 0)
+        end
+
+        def failure_result(outcome, cfg, record_path, event_id, message)
+          ReportResult.new(outcome: outcome, record_path: record_path, event_id: event_id,
+            delivery: nil, created_event: !event_id.nil?, message: message, exit_code: 1)
+        end
+
+        def finish_result(outcome, cfg, record_path, event_id, delivery, created_event)
+          if outcome.success?
+            message = "outcome recorded: success at #{record_path}"
+            message += delivery ? "; #{delivery}" : "; delivery not attempted"
+            ReportResult.new(outcome: outcome, record_path: record_path, event_id: event_id,
+              delivery: delivery, message: message, created_event: created_event, exit_code: 0)
+          else
+            message = "outcome recorded: error at #{record_path}"
+            message += "; #{delivery}" if delivery
+            ReportResult.new(outcome: outcome, record_path: record_path, event_id: event_id,
+              delivery: delivery, message: message, created_event: created_event, exit_code: 1)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/config_loader"
+require_relative "../molecules/task_probe"
+require_relative "../molecules/assignment_metadata"
+require_relative "../molecules/assignment_probe"
+require_relative "../molecules/step_evidence_reader"
+require_relative "../molecules/step_report_reader"
+require_relative "../molecules/git_state_probe"
+require_relative "../molecules/report_state_store"
+require_relative "../atoms/resume_planner"
+require_relative "report_orchestrator"
+
+module Ace
+  module Coworker
+    module Organisms
+      # Orchestrates `ace-coworker resume`: after an interruption, read the
+      # existing assignment, task, and the REAL state of the same worktree,
+      # and return to the remaining work. Same task/assignment/worktree —
+      # never a new one; local changes are never reset; resume itself never
+      # drives assignment steps. When the assignment is complete and only
+      # delivery is missing, delegates to ReportOrchestrator (same event ID
+      # resend). No journal/checkpoint store (ADR-034).
+      class ResumeOrchestrator
+        ResumeResult = Struct.new(:plan, :report_result, :message, :exit_code, keyword_init: true)
+
+        def initialize(project_root: nil, config_loader: nil, task_probe: nil,
+          assignment_probe: nil, evidence_reader: nil, report_reader: nil,
+          git_probe: nil, state_store: nil, report_orchestrator: nil, config: nil)
+          @config = config || Ace::Coworker.config
+          @project_root = project_root || Molecules::ProjectRoot.new.resolve
+          @config_loader = config_loader || Molecules::ConfigLoader.new(project_root: @project_root, defaults: @config)
+          @task_probe = task_probe || Molecules::TaskProbe.new(project_root: @project_root)
+          @assignment_metadata = Molecules::AssignmentMetadata.new(project_root: @project_root)
+          @assignment_probe = assignment_probe || Molecules::AssignmentProbe.new(project_root: @project_root)
+          @evidence_reader = evidence_reader || Molecules::StepEvidenceReader.new(project_root: @project_root)
+          @report_reader = report_reader || Molecules::StepReportReader.new(project_root: @project_root)
+          @git_probe = git_probe || Molecules::GitStateProbe.new(project_root: @project_root)
+          @state_store_factory = state_store
+          @report_orchestrator = report_orchestrator
+        end
+
+        # @return [ResumeResult]
+        def call(config_path: nil, assignment: nil, dry_run: false)
+          cfg = @config_loader.load(path: config_path)
+          assignment_id = assignment.to_s.strip.empty? ? cfg.assignment : assignment.to_s.strip
+          @task_probe.resolve!(cfg.task)
+          @assignment_metadata.verify_task_match!(assignment_id, cfg.task)
+          snapshot = @assignment_probe.snapshot(assignment_id)
+
+          state_store = @state_store_factory || Molecules::ReportStateStore.new(project_root: @project_root)
+          report_state = state_store.read(assignment_id)
+          git_state = @git_probe.state
+
+          in_flight_number = in_flight_step_number(snapshot)
+          step_cause = @evidence_reader.read(assignment_id, in_flight_number)
+          step_report = @report_reader.read(assignment_id, in_flight_number)
+
+          plan = Atoms::ResumePlanner.plan(snapshot: snapshot,
+            report_state: report_state, git_state: git_state,
+            step_cause: step_cause,
+            step_report_path: step_report && step_report["path"])
+
+          case plan.disposition
+          when :continue, :complete
+            ResumeResult.new(plan: plan,
+              message: plan.continue? ? "assignment in progress; resume the remaining work" : "assignment complete and delivered; nothing to resume",
+              exit_code: 0)
+          when :report
+            return ResumeResult.new(plan: plan,
+              message: "assignment complete; report delivery missing (dry-run: nothing sent)",
+              exit_code: 0) if dry_run
+
+            orchestrator = @report_orchestrator || ReportOrchestrator.new(project_root: @project_root, config: @config)
+            report_result = orchestrator.call(config_path: config_path, assignment: assignment_id)
+            action = report_result.created_event ? "reporting the outcome" : "redelivering the report"
+            ResumeResult.new(plan: plan, report_result: report_result,
+              message: "assignment complete; #{action}: #{report_result.message}",
+              exit_code: report_result.exit_code)
+          end
+        end
+
+        private
+
+        def in_flight_step_number(snapshot)
+          Atoms::ResumePlanner.in_flight_step(snapshot)&.number
+        end
+      end
+    end
+  end
+end