ace-overseer 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +26 -0
  3. data/README.md +2 -2
  4. data/docs/getting-started.md +1 -1
  5. data/docs/usage.md +47 -25
  6. data/handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md +258 -40
  7. data/handbook/workflow-instructions/overseer/lab-start.wf.md +60 -24
  8. data/handbook/workflow-instructions/overseer/queue.wf.md +33 -13
  9. data/handbook/workflow-instructions/overseer/start.wf.md +198 -21
  10. data/lib/ace/overseer/atoms/observation_sources.rb +17 -0
  11. data/lib/ace/overseer/atoms/report_interpretation.rb +28 -14
  12. data/lib/ace/overseer/atoms/start_contract.rb +20 -0
  13. data/lib/ace/overseer/cli/commands/handoff.rb +4 -0
  14. data/lib/ace/overseer/cli/commands/process_reports.rb +4 -2
  15. data/lib/ace/overseer/cli/commands/start.rb +37 -5
  16. data/lib/ace/overseer/cli/commands/work_on.rb +6 -2
  17. data/lib/ace/overseer/cli.rb +2 -0
  18. data/lib/ace/overseer/molecules/coworker_launcher.rb +189 -0
  19. data/lib/ace/overseer/molecules/event_observation.rb +54 -19
  20. data/lib/ace/overseer/molecules/eyes_evidence.rb +103 -0
  21. data/lib/ace/overseer/molecules/eyes_readiness.rb +21 -0
  22. data/lib/ace/overseer/molecules/eyes_session_evidence.rb +132 -0
  23. data/lib/ace/overseer/molecules/hitl_inbox.rb +14 -5
  24. data/lib/ace/overseer/molecules/local_sources.rb +83 -19
  25. data/lib/ace/overseer/molecules/project_bundle.rb +50 -6
  26. data/lib/ace/overseer/molecules/project_observations.rb +82 -0
  27. data/lib/ace/overseer/molecules/project_sessions.rb +99 -0
  28. data/lib/ace/overseer/molecules/remote_sources.rb +46 -16
  29. data/lib/ace/overseer/molecules/report_completion_check.rb +52 -0
  30. data/lib/ace/overseer/molecules/session_environment.rb +126 -0
  31. data/lib/ace/overseer/organisms/handoff_orchestrator.rb +26 -15
  32. data/lib/ace/overseer/organisms/report_processor.rb +56 -11
  33. data/lib/ace/overseer/organisms/start_orchestrator.rb +107 -52
  34. data/lib/ace/overseer/organisms/work_on_orchestrator.rb +43 -1
  35. data/lib/ace/overseer/version.rb +1 -1
  36. data/lib/ace/overseer.rb +3 -1
  37. metadata +65 -2
@@ -6,12 +6,10 @@ require "json"
6
6
  module Ace
7
7
  module Overseer
8
8
  module Molecules
9
- # Remote PR/repo observation (task 8xs.t.pu0.4): projects configured
10
- # pull requests through the EXISTING forge provider adapters
9
+ # Remote issue and PR observation through the existing forge adapters
11
10
  # (Ace::Git::Providers.for — Forgejo and GitHub; no separate HTTP
12
- # client here). Observed PRs come from the project's own
13
- # configuration (`observe.remote.pull_requests` in the overseer
14
- # cascade) — never a scan of every accessible account.
11
+ # client here). Observed repositories and PRs come from the project's
12
+ # own configuration — never a scan of every accessible account.
15
13
  #
16
14
  # Rows follow the standing-observation contract of LocalSources:
17
15
  # stable key + SEMANTIC revision (state, head SHA, review/comment
@@ -26,6 +24,8 @@ module Ace
26
24
  # class wakes once per failure mode, never as an empty healthy
27
25
  # list — and recovery re-observes the real state.
28
26
  class RemoteSources
27
+ ISSUE_LIMIT = 500
28
+
29
29
  def initialize(provider_factory: nil, timeout: nil)
30
30
  @provider_factory = provider_factory || ->(server_name) {
31
31
  server = Ace::Git::ServerRegistry.resolve(server_name)
@@ -35,8 +35,9 @@ module Ace
35
35
 
36
36
  # @param pull_requests [Array<Hash>] {"server" =>, "number" =>}
37
37
  # entries from the project's observe.remote configuration
38
+ # @param issues [Array<Hash>] {"server" =>} repository entries
38
39
  # @return [Hash] {"events" => Array, "sources" => {name => health}}
39
- def call(pull_requests:)
40
+ def call(pull_requests:, issues: [])
40
41
  sources = {}
41
42
  events = []
42
43
 
@@ -46,16 +47,9 @@ module Ace
46
47
  valid, invalid = Array(pull_requests).partition do |entry|
47
48
  entry.is_a?(Hash) && !entry["server"].to_s.empty? && !entry["number"].to_s.empty?
48
49
  end
49
- invalid.group_by { |entry| entry.is_a?(Hash) ? entry["server"].to_s : "" }.each do |server, entries|
50
- if server.empty?
51
- # Non-Hash or server-less entries still surface as health
52
- # markers, never silently disappear.
53
- sources["observe.remote"] ||= {"state" => "degraded",
54
- "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
55
- else
56
- sources["pr:#{server}"] ||= {"state" => "degraded",
57
- "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
58
- end
50
+ unless invalid.empty?
51
+ index = Array(pull_requests).index(invalid.first)
52
+ collect(sources, events, "pr:configuration") { raise ArgumentError, "invalid observe.remote.pull_requests entry at index #{index}" }
59
53
  end
60
54
 
61
55
  valid.group_by { |entry| entry["server"] }.each do |server, entries|
@@ -64,11 +58,47 @@ module Ace
64
58
  end
65
59
  end
66
60
 
61
+ Array(issues).each_with_index do |entry, index|
62
+ unless entry.is_a?(Hash) && entry["server"].is_a?(String) && !entry["server"].strip.empty?
63
+ unless sources.key?("issues:configuration")
64
+ collect(sources, events, "issues:configuration") { raise ArgumentError, "invalid observe.remote.issues entry at index #{index}" }
65
+ end
66
+ next
67
+ end
68
+
69
+ server = entry["server"]
70
+ next if sources.key?("issues:#{server}")
71
+
72
+ collect(sources, events, "issues:#{server}") { [issue_snapshot(server)] }
73
+ end
74
+
67
75
  {"events" => events, "sources" => sources}
68
76
  end
69
77
 
70
78
  private
71
79
 
80
+ # A single collection revision also detects a closed/deleted issue,
81
+ # which would simply disappear if each open issue had its own row.
82
+ # Refuse a truncated collection instead of silently missing work. The
83
+ # provider must paginate completely and return min(limit, total).
84
+ def issue_snapshot(server)
85
+ provider = @provider_factory.call(server)
86
+ unless provider.respond_to?(:recent_issues)
87
+ raise Ace::Git::ProviderUnsupportedCapabilityError,
88
+ "the selected provider has no issue-listing API; issues are unavailable, not empty"
89
+ end
90
+ issues = provider.recent_issues(limit: ISSUE_LIMIT + 1)
91
+ raise ArgumentError, "too many open issues to observe completely" if issues.length > ISSUE_LIMIT
92
+
93
+ items = issues.map do |issue|
94
+ {"number" => issue.number, "title" => issue.title, "body" => issue.body, "state" => issue.state.to_s,
95
+ "author" => issue.author, "url" => issue.url, "labels" => Array(issue.labels).map(&:to_s).sort}
96
+ end.sort_by { |item| item.fetch("number") }
97
+ {"key" => "issues:#{server}", "revision" => digest(items), "type" => "issues",
98
+ "forge" => server, "count" => items.length,
99
+ "issue_numbers" => items.first(20).map { |item| item.fetch("number") }}
100
+ end
101
+
72
102
  def collect(sources, events, name)
73
103
  rows = yield
74
104
  sources[name] = {"status" => "ok"}
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Ace
4
+ module Overseer
5
+ module Molecules
6
+ # Read existing coworker allocation and ace-assign completion truth before
7
+ # the queue accepts success. This check owns no persisted state.
8
+ class ReportCompletionCheck
9
+ def initialize(handoff_probe: nil, assignment_probe_factory: nil, worktree_finder: nil)
10
+ @worktree_finder = worktree_finder || Ace::Git::Worktree::Organisms::WorktreeManager.new
11
+ @handoff_probe = handoff_probe || HandoffProbe.new
12
+ @assignment_probe_factory = assignment_probe_factory || ->(root) {
13
+ Ace::Coworker::Molecules::AssignmentProbe.new(project_root: root)
14
+ }
15
+ end
16
+
17
+ def call(event:, manager:, step:)
18
+ return "matched task allocation no longer exists" unless manager && step
19
+ assignment = event["assignment"].to_s
20
+ if assignment.empty?
21
+ return nil if step.metadata["role"] == "planner" && step.metadata["assignment"].to_s.empty?
22
+ return "unassigned readiness is not execution completion"
23
+ end
24
+ task = manager.metadata["project_task"].to_s
25
+ role = step.metadata["role"].to_s
26
+ worktree = step.metadata["worktree"].to_s
27
+ worktree = manager.metadata["worktree"].to_s if worktree.empty?
28
+ return "success requires recorded project task, role and worktree" if [task, role, worktree].any?(&:empty?)
29
+ return "report task disagrees with the allocation" unless event["task"].to_s == task
30
+ return "confirm-start requires coordinator session evidence" if role == "confirm-start"
31
+ return "report assignment disagrees with the allocation" unless step.metadata["assignment"].to_s == assignment
32
+
33
+ found = @worktree_finder.switch(task)
34
+ return "task has no usable worktree: #{found[:error] || found[:message]}" unless found[:success]
35
+ root = found.fetch(:worktree_path)
36
+ legs = @handoff_probe.probe(root, task_id: task).fetch(:legs)
37
+ matching = legs.select { |leg| leg["assignment"] == assignment }
38
+ return "assignment has no unique allocation for this task" unless matching.size == 1
39
+ return "assignment role disagrees with the recorded allocation" unless matching.first["role"] == role
40
+ return "report role disagrees with the allocation" unless event["role"].to_s.empty? || event["role"] == role
41
+
42
+ snapshot = @assignment_probe_factory.call(root).snapshot(assignment)
43
+ return "assignment owner returned a different identity" unless snapshot.id == assignment
44
+ return "assignment is not complete: #{snapshot.incomplete_reasons.join('; ')}" unless snapshot.completion_verdict == :complete
45
+ nil
46
+ rescue Ace::Coworker::Error, Ace::Overseer::Error, SystemCallError, KeyError, Psych::Exception => e
47
+ "assignment completion could not be verified in #{worktree}: #{e.message}"
48
+ end
49
+ end
50
+ end
51
+ end
52
+ end
@@ -0,0 +1,126 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "fileutils"
5
+ require "tmpdir"
6
+ require "tempfile"
7
+ require "ace/lab/auth/session_configuration"
8
+ require "ace/support/cli/toolchain"
9
+
10
+ module Ace::Overseer::Molecules
11
+ # Passive deployment data becomes an explicit environment for one ordinary
12
+ # child. Files here are transient credentials, not a session state store.
13
+ class SessionEnvironment
14
+ BASE_KEYS = %w[HOME USER LOGNAME SHELL TERM LANG LC_ALL TZ TMPDIR PATH GEM_HOME GEM_PATH ACE_TOOLCHAIN
15
+ HERDR_SOCKET_PATH HERDR_WORKSPACE_ID].freeze
16
+ RESERVED = %w[ACE_TOOLCHAIN GEM_HOME GEM_PATH PATH PI_CODING_AGENT_DIR ACE_SESSION_CREDENTIALS_DIRECTORY BUNDLE_GEMFILE RUBYOPT RUBYLIB].freeze
17
+ MAX_BYTES = 65_536
18
+ ENVIRONMENT_ROLES = {"reviewer" => "verifier", "bootstrap-verifier" => "verifier", "bootstrap-worker" => "worker"}.freeze
19
+
20
+ def initialize(env: ENV, manifest_loader: -> { Ace::Lab::Molecules::InstallManifestLoader.load },
21
+ manifest_path: Ace::Lab.install_manifest_path)
22
+ @env, @loader, @manifest_path = env, manifest_loader, manifest_path
23
+ end
24
+
25
+ def with_environment(root:, role:)
26
+ environment = @env.to_h.slice(*BASE_KEYS)
27
+ directory = nil
28
+ handed_off = false
29
+ args = []
30
+ if @env["ACE_TOOLCHAIN"] == "installed"
31
+ selection = selection_for(root, role)
32
+ runtime = selection.runtime
33
+ args = ["--model", "#{runtime.fetch('provider')}/#{runtime.fetch('model')}"]
34
+ [runtime.fetch("node"), runtime.fetch("pi")].each do |path|
35
+ raise Ace::Overseer::Error, "installed runtime executable is unavailable: #{path}" unless File.executable?(path)
36
+ end
37
+ directory = Dir.mktmpdir("ace-session-")
38
+ File.chmod(0o700, directory)
39
+ provider = runtime.fetch("provider")
40
+ auth = read_private_json(runtime.fetch("credentials"))
41
+ raise Ace::Overseer::Error, "model provider credentials are unavailable" unless auth[provider].is_a?(Hash) && !auth[provider].empty?
42
+ write_private(File.join(directory, "auth.json"), provider => auth.fetch(provider))
43
+ write_private(File.join(directory, "settings.json"), "defaultProjectTrust" => "never")
44
+ environment = configured_environment(selection)
45
+ environment.merge!("PI_CODING_AGENT_DIR" => directory, "ACE_SESSION_CREDENTIALS_DIRECTORY" => directory)
46
+ else
47
+ environment.merge!(ProjectBundle.environment(root, env: @env)).compact!
48
+ end
49
+ Tempfile.create(["ace-environment-", ".json"]) do |file|
50
+ file.chmod(0o600)
51
+ file.write(JSON.generate(environment))
52
+ file.flush
53
+ file.fsync
54
+ handed_off = true
55
+ yield file.path, directory, args
56
+ end
57
+ rescue StandardError
58
+ FileUtils.remove_entry(directory) if !handed_off && directory && File.directory?(directory)
59
+ raise
60
+ end
61
+
62
+ # A projection needs this project's read credentials and installed CLI,
63
+ # not the coordinator's token or a new model-auth directory per poll.
64
+ def observation_environment(root:)
65
+ configured_environment(selection_for(root, "project-overseer"))
66
+ end
67
+
68
+ def self.cleanup(directory)
69
+ return unless directory
70
+ # Only our exact scratch directory; never a caller's home/config root.
71
+ unless File.absolute_path(directory) == directory && File.dirname(directory) == Dir.tmpdir.chomp(File::SEPARATOR) &&
72
+ File.basename(directory).start_with?("ace-session-") && !File.symlink?(directory)
73
+ raise Ace::Overseer::Error, "invalid session credential directory"
74
+ end
75
+ # Pi's transcript may live beside auth.json. Keep execution evidence.
76
+ File.unlink(File.join(directory, "auth.json")) if File.file?(File.join(directory, "auth.json"))
77
+ end
78
+
79
+ private
80
+
81
+ def selection_for(root, role)
82
+ raise Ace::Overseer::Error, "installed deployment manifest is unavailable" unless File.file?(@manifest_path)
83
+ document = @loader.call
84
+ project = ([document["coordinator"]] + document.fetch("projects")).compact.find do |entry|
85
+ root == entry["path"] || root.start_with?("#{entry['path']}/.ace-wt/")
86
+ end
87
+ raise Ace::Overseer::Error, "execution directory is not a configured project" unless project
88
+ Ace::Lab::Auth::SessionConfiguration.new(loader: -> { document }).resolve(
89
+ project: project.fetch("id"), role: ENVIRONMENT_ROLES.fetch(role, role))
90
+ end
91
+
92
+ def configured_environment(selection)
93
+ environment = @env.to_h.slice(*BASE_KEYS)
94
+ if selection.environment_file
95
+ values = read_private_json(selection.environment_file)
96
+ unless values.all? { |key, value| key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/) && value.is_a?(String) && !value.include?("\0") } &&
97
+ (values.keys & RESERVED).empty? && values.keys.none? { |key| key.start_with?("BUNDLE", "BUNDLER_") }
98
+ raise Ace::Overseer::Error, "role environment contains invalid or reserved variables"
99
+ end
100
+ environment.merge!(values)
101
+ end
102
+ runtime = selection.runtime
103
+ environment.merge("ACE_TOOLCHAIN" => "installed", "GEM_HOME" => selection.gem_home,
104
+ "GEM_PATH" => selection.gem_home,
105
+ "PATH" => ([File.join(selection.gem_home, "bin"), File.dirname(runtime.fetch("node")), File.dirname(runtime.fetch("pi"))] + runtime.fetch("path")).uniq.join(File::PATH_SEPARATOR))
106
+ end
107
+
108
+ def read_private_json(path)
109
+ File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
110
+ stat = file.stat
111
+ unless stat.file? && [0, Process.uid].include?(stat.uid) && (stat.mode & 0o777) == 0o600 && stat.size <= MAX_BYTES
112
+ raise Ace::Overseer::Error, "credential source must be a private regular file"
113
+ end
114
+ value = JSON.parse(file.read(MAX_BYTES + 1), create_additions: false, max_nesting: 8)
115
+ raise Ace::Overseer::Error, "credential source must be a JSON object" unless value.is_a?(Hash)
116
+ value
117
+ end
118
+ rescue JSON::ParserError, SystemCallError
119
+ raise Ace::Overseer::Error, "configured credential source is unavailable or invalid"
120
+ end
121
+
122
+ def write_private(path, value)
123
+ File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write(JSON.generate(value)) }
124
+ end
125
+ end
126
+ end
@@ -1,4 +1,5 @@
1
1
  # frozen_string_literal: true
2
+ require_relative "../molecules/coworker_launcher"
2
3
 
3
4
  module Ace
4
5
  module Overseer
@@ -20,13 +21,14 @@ module Ace
20
21
  # worktrees and hand off independently.
21
22
  class HandoffOrchestrator
22
23
  def initialize(task_loader: nil, worktree_finder: nil, probe: nil,
23
- window_opener: nil, config: nil, lifecycle_exclusion: nil)
24
+ window_opener: nil, config: nil, lifecycle_exclusion: nil, coworker_launcher: nil)
24
25
  @task_manager = task_loader || Ace::Task::Organisms::TaskManager.new
25
26
  @worktree_finder = worktree_finder
26
27
  @probe = probe
27
28
  @window_opener = window_opener || Molecules::WindowOpener.new
28
29
  @config = config || Ace::Overseer.config
29
30
  @lifecycle_exclusion = lifecycle_exclusion
31
+ @coworker_launcher = coworker_launcher
30
32
  end
31
33
 
32
34
  # @param task_ref [String] task reference (the task whose
@@ -56,19 +58,21 @@ module Ace
56
58
 
57
59
  outcome = nil
58
60
  lifecycle_exclusion.with_shared(lifecycle_exclusion.task_key(task.id.to_s)) do
59
- progress.call("Reading role-sequence state in #{worktree_path}...")
60
- state = probe.probe(worktree_path, task_id: task.id.to_s)
61
+ lifecycle_exclusion.with_exclusive("delegate:#{task.id}") do
62
+ progress.call("Reading role-sequence state in #{worktree_path}...")
63
+ state = probe.probe(worktree_path, task_id: task.id.to_s)
61
64
 
62
- active = Ace::Coworker::Atoms::ActiveExecutorRule.evaluate(
63
- config: state[:executor][:config], assignments: state[:executor][:assignments])
64
- verdict = Atoms::HandoffReadiness.evaluate(legs: state[:legs], active_executor: active)
65
+ active = Ace::Coworker::Atoms::ActiveExecutorRule.evaluate(
66
+ config: state[:executor][:config], assignments: state[:executor][:assignments])
67
+ verdict = Atoms::HandoffReadiness.evaluate(legs: state[:legs], active_executor: active)
65
68
 
66
- if verdict[:status] == :refused
67
- raise Error, "Handoff refused: #{verdict[:reasons].join("; ")}"
68
- end
69
+ if verdict[:status] == :refused
70
+ raise Error, "Handoff refused: #{verdict[:reasons].join("; ")}"
71
+ end
69
72
 
70
- outcome = ready_outcome(task: task, worktree_path: worktree_path, branch: found[:branch],
71
- verdict: verdict, dry_run: dry_run, runtime: runtime, progress: progress)
73
+ outcome = ready_outcome(task: task, worktree_path: worktree_path, branch: found[:branch],
74
+ verdict: verdict, dry_run: dry_run, runtime: runtime, progress: progress)
75
+ end
72
76
  end
73
77
 
74
78
  outcome
@@ -78,13 +82,20 @@ module Ace
78
82
 
79
83
  def ready_outcome(task:, worktree_path:, branch:, verdict:, dry_run:, runtime:, progress:)
80
84
  next_leg = verdict[:next]
85
+ execution = nil
81
86
 
82
87
  if next_leg
83
88
  progress.call("Next leg: role #{next_leg['role']} (assignment #{next_leg['assignment']})")
84
89
  unless dry_run
85
- window_options = {worktree_path: worktree_path, preset: @config.dig("window_presets", "handoff")}
86
- window_options[:runtime] = runtime if runtime
87
- @window_opener.open(**window_options)
90
+ selected = Atoms::RuntimeSetting.normalize(runtime || @config["runtime"]) || ENV["ACE_RUNTIME"]
91
+ if selected == "herdr" || selected.to_s.empty? && Ace::Runtime::Atoms::Detector.detect == :herdr
92
+ launcher = @coworker_launcher || Molecules::CoworkerLauncher.new
93
+ execution = launcher.call(worktree_path: worktree_path, config_path: next_leg.fetch("start_config"))
94
+ else
95
+ window_options = {worktree_path: worktree_path, preset: @config.dig("window_presets", "handoff")}
96
+ window_options[:runtime] = runtime if runtime
97
+ @window_opener.open(**window_options)
98
+ end
88
99
  end
89
100
  else
90
101
  progress.call("Every role in the sequence finished; nothing to hand off")
@@ -102,7 +113,7 @@ module Ace
102
113
  "start_config" => next_leg["start_config"]
103
114
  },
104
115
  dry_run: dry_run
105
- }
116
+ }.merge(execution ? {execution: execution} : {})
106
117
  end
107
118
 
108
119
  def worktree_finder
@@ -8,19 +8,21 @@ module Ace
8
8
  # the outcome through the existing ace-task update surface, and
9
9
  # continue the queue by reusing the existing start gates —
10
10
  # WorkOnOrchestrator for a step without a worktree,
11
- # HandoffOrchestrator for the next role in the SAME worktree. No new
12
- # state: the processed report ID lives on the step's frontmatter, so
11
+ # HandoffOrchestrator for the next role in the SAME worktree.
12
+ # No new state: the processed report ID lives on the step's frontmatter, so
13
13
  # a repeated delivery is detected from the recorded result instead
14
14
  # of re-running anything, and a question or failed report never
15
15
  # advances a step.
16
16
  class ReportProcessor
17
17
  OUTCOME_STATUSES = %i[success error needs_answer duplicate unmatched].freeze
18
18
 
19
- def initialize(inbox: nil, task_manager: nil, handoff: nil, work_on: nil)
20
- @inbox = inbox || Molecules::HitlInbox.new
19
+ def initialize(inbox: nil, task_manager: nil, handoff: nil, work_on: nil, completion_check: nil, owner: "overseer", scope: nil, retire: nil)
20
+ @completion_check = completion_check || Molecules::ReportCompletionCheck.new
21
+ @inbox = inbox || Molecules::HitlInbox.new(owner: owner, scope: scope)
21
22
  @task_manager = task_manager || Ace::Task::Organisms::TaskManager.new
22
23
  @handoff = handoff || Organisms::HandoffOrchestrator.new(task_loader: @task_manager)
23
24
  @work_on = work_on || Organisms::WorkOnOrchestrator.new(task_loader: @task_manager)
25
+ @retire = retire || Molecules::CoworkerLauncher.new.method(:retire)
24
26
  end
25
27
 
26
28
  # @param dry_run [Boolean] interpret only — no task writes, no
@@ -45,6 +47,12 @@ module Ace
45
47
  def process_event(event, dry_run:, progress:)
46
48
  verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: private_managers)
47
49
 
50
+ if verdict[:status] == :success || (verdict[:status] == :duplicate && verdict[:recorded_result] == "success")
51
+ refusal = @completion_check.call(event: event,
52
+ manager: @task_manager.show(verdict[:manager_ref]), step: @task_manager.show(verdict[:step_ref]))
53
+ verdict = {status: :unmatched, reason: refusal} if refusal
54
+ end
55
+
48
56
  case verdict[:status]
49
57
  when :unmatched
50
58
  progress.call("Event #{event['id']}: #{verdict[:reason]}")
@@ -72,8 +80,13 @@ module Ace
72
80
  # through the same gates; duplicate starts stay impossible because
73
81
  # the gates read real allocation state (work-on reuses an active
74
82
  # assignment, handoff refuses a busy worktree). A duplicate
75
- # without a recorded success (or a dry run) changes nothing.
83
+ # without a recorded success never continues work, but retries any
84
+ # incomplete executor cleanup. A dry run changes nothing.
76
85
  def resume_duplicate_continuation(verdict, event, dry_run:, progress:)
86
+ unless dry_run
87
+ retirement = retire_executor(verdict, event)
88
+ return outcome(verdict, event, retirement, retirement[:reason]) if retirement
89
+ end
77
90
  unless verdict[:recorded_result] == Atoms::ReportInterpretation::SUCCESS_RESULT && !dry_run
78
91
  return outcome(verdict, event, nil,
79
92
  "report #{event['id']} already recorded on #{verdict[:step_ref]} (result: #{verdict[:recorded_result]}); " \
@@ -102,6 +115,8 @@ module Ace
102
115
  return outcome(verdict, event, {action: "blocked", reason: reason}, message)
103
116
  end
104
117
  progress.call("Event #{event['id']}: recorded #{verdict[:status]} on #{verdict[:step_ref]}")
118
+ retirement = retire_executor(verdict, event)
119
+ return outcome(verdict, event, retirement, retirement[:reason]) if retirement
105
120
 
106
121
  if verdict[:status] == :error
107
122
  message = "step #{verdict[:step_ref]} kept open; report #{event['id']} (result #{verdict.dig(:set, Atoms::ReportInterpretation::REPORT_RESULT_KEY)}) " \
@@ -135,14 +150,21 @@ module Ace
135
150
  return {action: "none", reason: reason}
136
151
  end
137
152
 
153
+ if next_step.metadata["role"] == "confirm-start"
154
+ return {action: "coordinator", step_ref: next_step.id.to_s,
155
+ reason: "confirm project first turn and active eyes through the standard start operation; keep this step and manager open until proven"}
156
+ end
157
+
138
158
  begin
139
159
  if family_worktree(manager)
140
160
  result = @handoff.call(task_ref: manager.metadata["project_task"].to_s)
161
+ record_allocation(next_step, result) if result[:execution]
141
162
  {action: "handoff", step_ref: next_step.id.to_s,
142
163
  next: result[:next], status: result[:status], worktree_path: result[:worktree_path],
143
- start_command: start_command_of(result[:next])}
164
+ execution: result[:execution], start_command: start_command_of(result[:next])}
144
165
  else
145
166
  result = @work_on.call(task_ref: next_step.id.to_s)
167
+ record_allocation(next_step, result) if result[:execution]
146
168
  {action: "work-on", step_ref: next_step.id.to_s,
147
169
  assignment_id: result[:assignment_id], worktree_path: result[:worktree_path],
148
170
  assignment_created: result.fetch(:assignment_created, true)}
@@ -153,6 +175,28 @@ module Ace
153
175
  end
154
176
  end
155
177
 
178
+ def retire_executor(verdict, event)
179
+ assignment = event["assignment"].to_s
180
+ return if assignment.empty?
181
+ step = @task_manager.show(verdict[:step_ref])
182
+ manager = @task_manager.show(verdict[:manager_ref])
183
+ root = step&.metadata&.fetch("worktree", nil) || (manager && family_worktree(manager))
184
+ return if root.to_s.empty?
185
+ @retire.call(worktree_path: File.expand_path(root), assignment: assignment)
186
+ nil
187
+ rescue Ace::Overseer::Error, Ace::Herdr::ExecutorError, Ace::Coworker::Error => e
188
+ {action: "blocked", reason: "report recorded; executor retirement failed: #{e.message}"}
189
+ end
190
+
191
+ def record_allocation(step, result)
192
+ execution = result.fetch(:execution)
193
+ unless @task_manager.update(step.id, set: {"assignment" => execution.fetch("assignment"),
194
+ "worktree" => result.fetch(:worktree_path), "terminal" => execution.fetch("terminal_id"),
195
+ "role" => execution.fetch("role")})
196
+ raise Ace::Overseer::Error, "executor started but allocation could not be recorded; reconcile before another start"
197
+ end
198
+ end
199
+
156
200
  # The actionable start command for the next handoff leg — exactly
157
201
  # what the Handoff CLI prints, never a rebuilt guess. nil when the
158
202
  # leg carries no probed start config (the handoff gate refuses to
@@ -209,15 +253,15 @@ module Ace
209
253
  }
210
254
  end
211
255
 
212
- # Per queue.wf.md section 4 the handoff gate only ENSURES the next
213
- # role's window in the worktree; the overseer AGENT runs the
214
- # printed start command. The description therefore carries the
215
- # command instead of asserting the role already started.
256
+ # Report an actual launch only when the handoff returned its binding.
257
+ # A prepared leg alone is not execution evidence.
216
258
  def continuation_description(continuation)
217
259
  case continuation[:action]
218
260
  when "handoff"
219
261
  if continuation[:status] == "sequence_complete"
220
- "sequence complete - the worktree has no next role; close the managing task per the queue workflow"
262
+ "sequence complete - the worktree has no next role; pending coordination steps still require acceptance before closing the managing task"
263
+ elsif continuation[:execution]
264
+ "executor #{continuation[:execution]['agent']} started; end the turn and await its report"
221
265
  elsif continuation[:start_command]
222
266
  "window ensured in #{continuation[:worktree_path]} for the next role " \
223
267
  "(#{continuation.dig(:next, 'role')}); run there: #{continuation[:start_command]}"
@@ -231,6 +275,7 @@ module Ace
231
275
  else
232
276
  "next step #{continuation[:step_ref]} started via work-on"
233
277
  end
278
+ when "coordinator" then "coordinator action for #{continuation[:step_ref]}: #{continuation[:reason]}"
234
279
  when "blocked" then "continuation blocked: #{continuation[:reason]}"
235
280
  when "none" then continuation[:reason]
236
281
  end