ace-overseer 0.28.1 → 0.30.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 (35) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +12 -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 +224 -37
  7. data/handbook/workflow-instructions/overseer/lab-start.wf.md +49 -21
  8. data/handbook/workflow-instructions/overseer/queue.wf.md +13 -8
  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/start_contract.rb +20 -0
  12. data/lib/ace/overseer/cli/commands/handoff.rb +4 -0
  13. data/lib/ace/overseer/cli/commands/process_reports.rb +4 -2
  14. data/lib/ace/overseer/cli/commands/start.rb +45 -5
  15. data/lib/ace/overseer/cli/commands/work_on.rb +6 -2
  16. data/lib/ace/overseer/cli.rb +2 -0
  17. data/lib/ace/overseer/molecules/coworker_launcher.rb +189 -0
  18. data/lib/ace/overseer/molecules/event_observation.rb +54 -19
  19. data/lib/ace/overseer/molecules/eyes_evidence.rb +103 -0
  20. data/lib/ace/overseer/molecules/eyes_readiness.rb +21 -0
  21. data/lib/ace/overseer/molecules/eyes_session_evidence.rb +132 -0
  22. data/lib/ace/overseer/molecules/hitl_inbox.rb +13 -5
  23. data/lib/ace/overseer/molecules/local_sources.rb +83 -19
  24. data/lib/ace/overseer/molecules/project_bundle.rb +1 -1
  25. data/lib/ace/overseer/molecules/project_observations.rb +82 -0
  26. data/lib/ace/overseer/molecules/project_sessions.rb +99 -0
  27. data/lib/ace/overseer/molecules/remote_sources.rb +46 -16
  28. data/lib/ace/overseer/molecules/session_environment.rb +127 -0
  29. data/lib/ace/overseer/organisms/handoff_orchestrator.rb +26 -15
  30. data/lib/ace/overseer/organisms/report_processor.rb +42 -10
  31. data/lib/ace/overseer/organisms/start_orchestrator.rb +105 -55
  32. data/lib/ace/overseer/organisms/work_on_orchestrator.rb +43 -1
  33. data/lib/ace/overseer/version.rb +1 -1
  34. data/lib/ace/overseer.rb +2 -1
  35. metadata +64 -2
@@ -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,20 +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, completion_check: nil)
19
+ def initialize(inbox: nil, task_manager: nil, handoff: nil, work_on: nil, completion_check: nil, owner: "overseer", scope: nil, retire: nil)
20
20
  @completion_check = completion_check || Molecules::ReportCompletionCheck.new
21
- @inbox = inbox || Molecules::HitlInbox.new
21
+ @inbox = inbox || Molecules::HitlInbox.new(owner: owner, scope: scope)
22
22
  @task_manager = task_manager || Ace::Task::Organisms::TaskManager.new
23
23
  @handoff = handoff || Organisms::HandoffOrchestrator.new(task_loader: @task_manager)
24
24
  @work_on = work_on || Organisms::WorkOnOrchestrator.new(task_loader: @task_manager)
25
+ @retire = retire || Molecules::CoworkerLauncher.new.method(:retire)
25
26
  end
26
27
 
27
28
  # @param dry_run [Boolean] interpret only — no task writes, no
@@ -79,8 +80,13 @@ module Ace
79
80
  # through the same gates; duplicate starts stay impossible because
80
81
  # the gates read real allocation state (work-on reuses an active
81
82
  # assignment, handoff refuses a busy worktree). A duplicate
82
- # 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.
83
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
84
90
  unless verdict[:recorded_result] == Atoms::ReportInterpretation::SUCCESS_RESULT && !dry_run
85
91
  return outcome(verdict, event, nil,
86
92
  "report #{event['id']} already recorded on #{verdict[:step_ref]} (result: #{verdict[:recorded_result]}); " \
@@ -109,6 +115,8 @@ module Ace
109
115
  return outcome(verdict, event, {action: "blocked", reason: reason}, message)
110
116
  end
111
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
112
120
 
113
121
  if verdict[:status] == :error
114
122
  message = "step #{verdict[:step_ref]} kept open; report #{event['id']} (result #{verdict.dig(:set, Atoms::ReportInterpretation::REPORT_RESULT_KEY)}) " \
@@ -150,11 +158,13 @@ module Ace
150
158
  begin
151
159
  if family_worktree(manager)
152
160
  result = @handoff.call(task_ref: manager.metadata["project_task"].to_s)
161
+ record_allocation(next_step, result) if result[:execution]
153
162
  {action: "handoff", step_ref: next_step.id.to_s,
154
163
  next: result[:next], status: result[:status], worktree_path: result[:worktree_path],
155
- start_command: start_command_of(result[:next])}
164
+ execution: result[:execution], start_command: start_command_of(result[:next])}
156
165
  else
157
166
  result = @work_on.call(task_ref: next_step.id.to_s)
167
+ record_allocation(next_step, result) if result[:execution]
158
168
  {action: "work-on", step_ref: next_step.id.to_s,
159
169
  assignment_id: result[:assignment_id], worktree_path: result[:worktree_path],
160
170
  assignment_created: result.fetch(:assignment_created, true)}
@@ -165,6 +175,28 @@ module Ace
165
175
  end
166
176
  end
167
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
+
168
200
  # The actionable start command for the next handoff leg — exactly
169
201
  # what the Handoff CLI prints, never a rebuilt guess. nil when the
170
202
  # leg carries no probed start config (the handoff gate refuses to
@@ -221,15 +253,15 @@ module Ace
221
253
  }
222
254
  end
223
255
 
224
- # Per queue.wf.md section 4 the handoff gate only ENSURES the next
225
- # role's window in the worktree; the overseer AGENT runs the
226
- # printed start command. The description therefore carries the
227
- # 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.
228
258
  def continuation_description(continuation)
229
259
  case continuation[:action]
230
260
  when "handoff"
231
261
  if continuation[:status] == "sequence_complete"
232
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"
233
265
  elsif continuation[:start_command]
234
266
  "window ensured in #{continuation[:worktree_path]} for the next role " \
235
267
  "(#{continuation.dig(:next, 'role')}); run there: #{continuation[:start_command]}"
@@ -1,11 +1,17 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "../atoms/start_contract"
4
+ require_relative "../atoms/observation_sources"
4
5
  require_relative "../molecules/project_root_resolver"
5
6
  require_relative "../molecules/project_bundle"
7
+ require_relative "../molecules/eyes_readiness"
8
+ require_relative "../molecules/session_environment"
6
9
  require "ace/herdr"
10
+ require "ace/herdr/molecules/installed_pi_extensions"
11
+ require "ace/lab"
7
12
  require "ace/support/cli/toolchain"
8
13
  require "json"
14
+ require "open3"
9
15
 
10
16
  module Ace
11
17
  module Overseer
@@ -39,15 +45,7 @@ module Ace
39
45
  # READY for input — the session begins its first turn when this
40
46
  # prompt arrives, exactly as the standing instructions' "First
41
47
  # turn after start" section describes (state read, /eyes arming).
42
- FIRST_TURN_PROMPT = <<~PROMPT.chomp
43
- Begin your first turn now. Follow the "First turn after start"
44
- section of your standing instructions: read your private
45
- _overseer tasks and the project state from its owners, continue
46
- existing commissioned work before choosing anything new. Arm
47
- standing observation with the ace_eyes tool, action start and
48
- configPath naming your eyes configuration; verify its returned
49
- observation state. Remain idle when there is nothing to do.
50
- PROMPT
48
+
51
49
 
52
50
  attr_reader :cwd
53
51
 
@@ -65,7 +63,8 @@ module Ace
65
63
  # lazily, only when a session actually boots.
66
64
  # @param cwd [String] invocation directory
67
65
  def initialize(config: nil, executor: nil, root_resolver: nil, nav_runner: nil,
68
- workspace: nil, workspace_factory: nil, cwd: Dir.pwd, env: ENV, scope: nil, project_runner: nil)
66
+ workspace: nil, workspace_factory: nil, cwd: Dir.pwd, env: ENV, scope: nil, project_runner: nil,
67
+ eyes_evidence: nil)
69
68
  @config = config || Ace::Overseer.config
70
69
  @executor = executor || Ace::Herdr::Molecules::HerdrExecutor.new
71
70
  @control_surface = Ace::Herdr::Organisms::ControlSurface.new(executor: @executor)
@@ -77,6 +76,7 @@ module Ace
77
76
  @env = env
78
77
  @scope = scope
79
78
  @project_runner = project_runner || Molecules::ProjectBundle.new
79
+ @eyes_evidence = eyes_evidence || Molecules::EyesReadiness.new(env: env)
80
80
  end
81
81
 
82
82
  # @param dry_run [Boolean] report the plan without creating a
@@ -111,11 +111,9 @@ module Ace
111
111
 
112
112
  state = agent_state(owner["id"])
113
113
  if state
114
- # a live agent is a PROCESS, not necessarily a completed
115
- # start — the missing first-turn initialization is
116
- # repaired through the existing session (see
117
- # repair_reused_initialization)
118
- warning = repair_reused_initialization(owner["id"], state)
114
+ # A live process does not prove that its first prompt was
115
+ # delivered. Never repeat an uncertain submission on reuse.
116
+ warning = reused_session_warning(state, pane: owner["id"], root: root)
119
117
  return report.merge("status" => "reused", "pane" => owner["id"],
120
118
  "workspace" => owner["workspace_id"] || owner["workspace"],
121
119
  "prompt_failed" => !warning.nil?,
@@ -134,7 +132,7 @@ module Ace
134
132
  report["workspace"] = workspace
135
133
 
136
134
  pane = boot_session(workspace, label, root, plan, instructions_path)
137
- prompt_warning = first_prompt(pane)
135
+ prompt_warning = first_prompt(pane, root)
138
136
  report.merge("status" => "started", "pane" => pane,
139
137
  "prompt_failed" => !prompt_warning.nil?,
140
138
  "message" => prompt_warning ||
@@ -166,13 +164,18 @@ module Ace
166
164
  end
167
165
  raise Ace::Overseer::Error, "standing instructions file is missing: #{guide}" unless File.file?(guide)
168
166
  command = ["pi", "--model", plan["profile"]["model"]]
167
+ command += Ace::Herdr::Molecules::InstalledPiExtensions.arguments
169
168
  thinking = plan["profile"]["thinking"]
170
169
  command += ["--thinking", thinking] if thinking
171
- command += ["--append-system-prompt", guide, FIRST_TURN_PROMPT]
170
+ command += ["--append-system-prompt", guide, Atoms::StartContract::FIRST_TURN_PROMPT]
172
171
  {"status" => dry_run ? "dry_run" : "foreground", "scope" => plan["scope"],
173
172
  "root" => root, "profile" => plan["profile_name"],
174
173
  "instructions" => {"source" => source, "path" => guide},
175
174
  "command" => command, "message" => "launch the coordinator in the current terminal"}
175
+ rescue Ace::Herdr::ExecutorError => e
176
+ blocked(e.message)
177
+ rescue SystemCallError => e
178
+ blocked("foreground start cannot access its working directory: #{e.class}")
176
179
  end
177
180
 
178
181
  # Explicit tool available to the running Lab agent. This operation
@@ -193,7 +196,7 @@ module Ace
193
196
  # id/path) — never from the sanitized public projection and
194
197
  # never derived from an id/label/repo name. The lab space hosts
195
198
  # ONLY the lab overseer session; EACH project boots in its OWN
196
- # herdr space (created/reused by the project's session label),
199
+ # herdr space (created/reused by its topology id),
197
200
  # so project sessions are isolated from each other and from the
198
201
  # lab overseer. Each project starts through the SAME operation
199
202
  # as a standalone start (its own cascade, its own session
@@ -268,7 +271,7 @@ module Ace
268
271
  # An empty configured list is a valid idle lab: the lab
269
272
  # overseer itself still runs (and must be initialized).
270
273
  if projects.empty?
271
- message = reconcile ? "no project children configured" : "no projects configured; the lab overseer is idle"
274
+ message = reconcile ? "no project children configured" : "no projects configured"
272
275
  message += "; #{session["message"]}" if session["message"]
273
276
  return base.merge("status" => lab_ready ? "ready" : "partial",
274
277
  "ready" => lab_ready, "project_count" => 0, "message" => message)
@@ -282,9 +285,10 @@ module Ace
282
285
  base.merge("status" => ready ? "ready" : "partial", "ready" => ready,
283
286
  "projects" => results, "project_count" => results.size,
284
287
  "message" => summary)
285
- rescue Ace::Overseer::Error, Ace::Herdr::ExecutorError => e
288
+ rescue Ace::Overseer::Error, Ace::Herdr::ExecutorError, SystemCallError => e
286
289
  # A lab-level failure keeps the lab context (scope/root/label)
287
290
  # so callers can tell it from a per-project blocked result.
291
+ base ||= blocked(nil).merge("scope" => "lab", "projects" => [], "project_count" => 0, "ready" => false)
288
292
  base.merge("status" => "blocked", "message" => "lab start failed: #{e.message}")
289
293
  end
290
294
 
@@ -351,7 +355,7 @@ module Ace
351
355
  end
352
356
  state = agent_state(owner["id"])
353
357
  if state
354
- warning = repair_reused_initialization(owner["id"], state)
358
+ warning = reused_session_warning(state, pane: owner["id"], root: lab_root)
355
359
  return {"status" => "reused", "pane" => owner["id"], "replaced_pane" => nil,
356
360
  "prompt_failed" => !warning.nil?, "message" => warning}
357
361
  end
@@ -360,7 +364,7 @@ module Ace
360
364
  end
361
365
 
362
366
  pane = boot_session(workspace, label, lab_root, plan, instructions_path)
363
- prompt_warning = first_prompt(pane)
367
+ prompt_warning = first_prompt(pane, lab_root)
364
368
  {"status" => "started", "pane" => pane, "replaced_pane" => replaced,
365
369
  "prompt_failed" => !prompt_warning.nil?, "message" => prompt_warning}
366
370
  rescue Ace::Overseer::Error => e
@@ -549,12 +553,12 @@ module Ace
549
553
  # confirmation comes from first_prompt's activity gate.
550
554
  def agent_state(pane)
551
555
  json = @executor.agent_get(pane).parsed_json
552
- return nil unless json.is_a?(Hash)
556
+ raise Ace::Overseer::Error, "herdr returned a malformed agent response; preserve the existing session" unless json.is_a?(Hash)
553
557
 
554
558
  agent = json["agent"]
555
559
  agent = json["result"]["agent"] if agent.nil? && json["result"].is_a?(Hash)
556
560
  agent = json["result"] if agent.nil? && json["result"].is_a?(Hash)
557
- return "" unless agent.is_a?(Hash)
561
+ raise Ace::Overseer::Error, "herdr returned no agent identity; preserve the existing session" unless agent.is_a?(Hash)
558
562
 
559
563
  agent["agent_status"].to_s
560
564
  rescue Ace::Herdr::AgentNotFoundError
@@ -576,18 +580,23 @@ module Ace
576
580
  "herdr created tab '#{label}' but reported no root pane"
577
581
  end
578
582
 
579
- Molecules::ProjectBundle.with_shell_setup(root, env: @env) do |command, marker|
580
- @executor.pane_run(pane, command)
581
- @executor.pane_wait_output(pane, pattern: marker, timeout_ms: START_TIMEOUT_MS)
582
- end
583
583
  args = ["--model", plan["profile"]["model"]]
584
584
  if plan["profile"]["thinking"]
585
585
  args += ["--thinking", plan["profile"]["thinking"]]
586
586
  end
587
587
  args += ["--append-system-prompt", instructions_path]
588
588
 
589
- @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
590
- pane: pane, timeout_ms: START_TIMEOUT_MS, args: args)
589
+ if @env["ACE_TOOLCHAIN"] == "installed"
590
+ role = plan["scope"] == "lab" ? "lab-overseer" : "project-overseer"
591
+ start_installed_agent(pane, root, role, plan, args)
592
+ else
593
+ Molecules::ProjectBundle.with_shell_setup(root, env: @env) do |command, marker|
594
+ @executor.pane_run(pane, command)
595
+ @executor.pane_wait_output(pane, pattern: marker, timeout_ms: START_TIMEOUT_MS)
596
+ end
597
+ @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
598
+ pane: pane, timeout_ms: START_TIMEOUT_MS, args: args)
599
+ end
591
600
  pane
592
601
  rescue Ace::Herdr::WaitTimeoutError => e
593
602
  raise Ace::Overseer::Error, "runtime setup was not confirmed; agent not started: #{e.message}"
@@ -595,45 +604,86 @@ module Ace
595
604
  raise Ace::Overseer::Error, "herdr failed to start the overseer session: #{e.message}"
596
605
  end
597
606
 
607
+ # A failed native start can still have created a process. Close the
608
+ # pane before deleting its credentials; if closure is unconfirmed,
609
+ # preserve the directory and report that recovery is required.
610
+ def start_installed_agent(pane, root, role, plan, args)
611
+ credentials = nil
612
+ Molecules::SessionEnvironment.new(env: @env).with_environment(root: root, role: role) do |file, directory, _profile|
613
+ credentials = directory
614
+ @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
615
+ pane: pane, timeout_ms: START_TIMEOUT_MS, args: args, env_file: file)
616
+ end
617
+ rescue StandardError, Interrupt
618
+ begin
619
+ @executor.pane_close(pane)
620
+ rescue Ace::Herdr::PaneNotFoundError
621
+ # Native owner confirms there is no surviving pane.
622
+ rescue Ace::Herdr::ExecutorError => cleanup_error
623
+ raise Ace::Overseer::Error, "coordinator start failed and pane cleanup is unconfirmed; preserve its credentials and inspect #{pane}: #{cleanup_error.message}"
624
+ end
625
+ Molecules::SessionEnvironment.cleanup(credentials)
626
+ raise
627
+ end
628
+
598
629
  # `agent start` success only means the interactive agent is
599
630
  # ready for input; the first prompt begins the session's first
600
631
  # turn (state read, /eyes arming). Delivery is CONFIRMED through
601
- # herdr's activity gate (`agent prompt --wait`): success means
602
- # herdr observed working/blocked activity, so the turn actually
603
- # began — a stall, timeout or pre-send failure is an uncertain
632
+ # herdr's activity gate (`agent prompt --wait`) observes activity;
633
+ # it does not prove that this exact prompt was consumed or that eyes
634
+ # are armed. A stall, timeout or pre-send failure is an uncertain
604
635
  # outcome, returned as a visible warning instead of a readiness
605
- # claim. Never raised: the agent itself is live and idle.
606
- def first_prompt(pane)
607
- @executor.agent_prompt(pane: pane, text: FIRST_TURN_PROMPT,
608
- wait: true, timeout_ms: FIRST_TURN_TIMEOUT_MS)
609
- nil
610
- rescue Ace::Herdr::ExecutorError => e
611
- "the agent is started and idle, but its first turn could not be " \
612
- "confirmed delivered (#{e.message}); re-run start to repair the " \
613
- "missing initialization"
636
+ # claim. The process exists, but may already have begun its turn.
637
+ def first_prompt(pane, root)
638
+ response = @executor.agent_prompt(pane: pane, text: Atoms::StartContract::FIRST_TURN_PROMPT,
639
+ wait: true, until_states: %w[working blocked], timeout_ms: FIRST_TURN_TIMEOUT_MS)
640
+ observed = response.parsed_json
641
+ result = observed.is_a?(Hash) ? observed["result"] : nil
642
+ agent = result.is_a?(Hash) && result["type"] == "agent_prompted" ? result["agent"] : nil
643
+ activity = agent.is_a?(Hash) ? agent["agent_status"] : nil
644
+ unless activity == "working"
645
+ detail = activity == "blocked" ? " (blocked)" : ""
646
+ return "the first prompt did not confirm working activity#{detail}; " \
647
+ "inspect the existing session before taking further action"
648
+ end
649
+ state = agent_state(pane)
650
+ unless %w[working idle done].include?(state)
651
+ description = state.nil? ? "unavailable" : (state.empty? ? "unknown" : state)
652
+ return "the agent is #{description}; its first turn or readiness " \
653
+ "cannot be confirmed — inspect the existing session before taking further action"
654
+ end
655
+ observation_warning(pane, root)
656
+ rescue Ace::Herdr::ExecutorError, Ace::Overseer::Error => e
657
+ "the agent is started, but its first turn could not be " \
658
+ "confirmed delivered (#{e.message}); inspect the existing session " \
659
+ "and resolve the uncertain delivery before taking further action"
614
660
  end
615
661
 
616
662
  # A REUSED live agent proves a process, not a completed start.
617
- # Classification through the existing herdr session state (no
618
- # parallel store): working/blocked = mid-conversation, the first
619
- # turn is already underway — never interrupted; idle/done =
620
- # ready for input — the first-turn prompt is (re-)delivered
621
- # through the existing session with the activity gate, which
622
- # repairs a missing initialization without restarting anything
623
- # (a healthy agent simply reconciles once and settles); any
624
- # other state is visibly unconfirmed, never a readiness claim.
625
- def repair_reused_initialization(pane, state)
663
+ # No process state distinguishes the original prompt from later
664
+ # activity, or proves that the standing observer is armed.
665
+ # Report uncertainty and preserve the session rather than resend.
666
+ def reused_session_warning(state, pane:, root:)
626
667
  case state
627
- when "working", "blocked"
628
- nil
629
- when "idle", "done"
630
- first_prompt(pane)
668
+ when "working", "idle", "done"
669
+ observation_warning(pane, root)
670
+ when "blocked"
671
+ "the reused agent is blocked and cannot be considered ready — inspect its pending decision or error"
631
672
  else
632
673
  "the reused agent state is '#{state}'; its first turn could not " \
633
674
  "be verified — inspect the session before relying on it"
634
675
  end
635
676
  end
636
677
 
678
+ def observation_warning(pane, root)
679
+ required = Atoms::ObservationSources::REQUIRED.dup
680
+ required << Atoms::ObservationSources::PROJECT_SESSIONS if File.file?(File.join(root, ".ace/lab/config.yml"))
681
+ return nil if @eyes_evidence.ready?(pane: pane, root: root, prompt: Atoms::StartContract::FIRST_TURN_PROMPT, required_sources: required)
682
+
683
+ "first turn and live eyes observation are not yet verified; required sources: #{required.join(", ")}; " \
684
+ "preserve the session and recheck after its state changes"
685
+ end
686
+
637
687
  def dig_pane(json)
638
688
  return nil unless json.is_a?(Hash)
639
689
 
@@ -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
@@ -8,7 +9,7 @@ module Ace
8
9
  SUBTASK_PATTERN = /^[0-9a-z]{3}\.[a-z]\.[0-9a-z]{3}\.[a-z0-9]$/
9
10
 
10
11
  def initialize(worktree_provisioner: nil, window_opener: nil, assignment_launcher: nil,
11
- task_loader: nil, config: nil, assignment_detector: nil, lifecycle_exclusion: nil)
12
+ task_loader: nil, config: nil, assignment_detector: nil, lifecycle_exclusion: nil, coworker_launcher: nil)
12
13
  @worktree_provisioner = worktree_provisioner || Molecules::WorktreeProvisioner.new
13
14
  @window_opener = window_opener || Molecules::WindowOpener.new
14
15
  @task_manager = task_loader || Ace::Task::Organisms::TaskManager.new
@@ -16,6 +17,7 @@ module Ace
16
17
  @config = config || Ace::Overseer.config
17
18
  @assignment_detector = assignment_detector
18
19
  @lifecycle_exclusion = lifecycle_exclusion
20
+ @coworker_launcher = coworker_launcher
19
21
  end
20
22
 
21
23
  def call(task_ref:, task_refs: nil, cli_preset: nil, on_progress: nil, runtime: nil)
@@ -39,6 +41,10 @@ module Ace
39
41
  primary_task = resolved_refs.first[:task]
40
42
 
41
43
  guard_dependencies_satisfied!(resolved_refs)
44
+ if native_delegation?(runtime)
45
+ raise Error, "delegate one task per worktree" unless resolved_refs.size == 1
46
+ return delegate(resolved_refs.first, progress: progress)
47
+ end
42
48
 
43
49
  preset_name = Atoms::PresetResolver.resolve(
44
50
  task_frontmatter: primary_task.respond_to?(:metadata) ? (primary_task.metadata || {}) : {},
@@ -118,6 +124,42 @@ module Ace
118
124
 
119
125
  private
120
126
 
127
+ def native_delegation?(runtime)
128
+ selected = Atoms::RuntimeSetting.normalize(runtime || @config["runtime"]) || ENV["ACE_RUNTIME"]
129
+ selected == "herdr" || selected.to_s.empty? && Ace::Runtime::Atoms::Detector.detect == :herdr
130
+ end
131
+
132
+ def delegate(entry, progress:)
133
+ launcher = @coworker_launcher || Molecules::CoworkerLauncher.new
134
+ launcher.ready!
135
+ ref = entry.fetch(:ref)
136
+ task = entry.fetch(:task)
137
+ lifecycle_exclusion.with_shared(lifecycle_exclusion.task_key(ref), reset_removed: true) do
138
+ lifecycle_exclusion.with_exclusive("delegate:#{ref}") do
139
+ worktree = @worktree_provisioner.provision(ref)
140
+ root = worktree.fetch(:worktree_path)
141
+ roles = task.metadata["roles"] || (task.metadata["role"] ? [task.metadata["role"]] : %w[worker reviewer integrator])
142
+ sequence = Ace::Coworker::Molecules::RoleSequenceComposer.new(project_root: root).call(task: task.id, roles: roles)
143
+ configs = Ace::Coworker::Organisms::StartConfigWriter.new(worktree_path: root).call(
144
+ task: task.id, sequence: sequence, overseer: @config["owner"] || launcher.recipient)
145
+ state = Molecules::HandoffProbe.new.probe(root, task_id: task.id)
146
+ leg = state.fetch(:legs).find { |candidate| candidate["state"] != "completed" }
147
+ raise Error, "all prepared roles are complete; reconcile the task instead of starting again" unless leg
148
+ unless %w[paused empty running].include?(leg["state"])
149
+ raise Error, "assignment #{leg['assignment']} is #{leg['state']}; investigate before dispatch"
150
+ end
151
+ config = configs.find { |row| row["assignment"] == leg["assignment"] }
152
+ raise Error, "prepared role has no start configuration" unless config
153
+ execution = launcher.call(worktree_path: root, config_path: config.fetch("path"))
154
+ progress.call("Executor #{execution['agent']} bound to assignment #{leg['assignment']}")
155
+ {task_ref: task.id, task_refs: [task.id], worktree_path: root, branch: worktree[:branch],
156
+ worktree_created: worktree[:created], assignment_id: leg["assignment"],
157
+ assignment_created: sequence.find { |row| row["assignment"] == leg["assignment"] }["disposition"] == "created",
158
+ execution: execution}
159
+ end
160
+ end
161
+ end
162
+
121
163
  # Overseer queue rule (L6.3): only steps whose recorded dependencies
122
164
  # are satisfied may start. Satisfaction requires a predecessor status
123
165
  # of "done" (accepted AND integrated result) -- a finished worker or
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Ace
4
4
  module Overseer
5
- VERSION = "0.28.1"
5
+ VERSION = "0.30.0"
6
6
  end
7
7
  end
data/lib/ace/overseer.rb CHANGED
@@ -37,6 +37,8 @@ require_relative "overseer/molecules/worktree_context_collector"
37
37
  require_relative "overseer/molecules/handoff_probe"
38
38
  require_relative "overseer/molecules/hitl_inbox"
39
39
  require_relative "overseer/molecules/report_completion_check"
40
+ require_relative "overseer/molecules/project_root_resolver"
41
+ require_relative "overseer/molecules/project_sessions"
40
42
  require_relative "overseer/molecules/local_sources"
41
43
  require_relative "overseer/molecules/remote_sources"
42
44
  require_relative "overseer/molecules/event_observation"
@@ -44,7 +46,6 @@ require_relative "overseer/molecules/preservation_manifest"
44
46
  require_relative "overseer/molecules/git_preservation_checker"
45
47
  require_relative "overseer/molecules/prune_safety_checker"
46
48
  require_relative "overseer/molecules/assignment_prune_safety_checker"
47
- require_relative "overseer/molecules/project_root_resolver"
48
49
  require_relative "overseer/organisms/work_on_orchestrator"
49
50
  require_relative "overseer/organisms/handoff_orchestrator"
50
51
  require_relative "overseer/organisms/report_processor"