ace-overseer 0.30.1 → 0.31.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 (36) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +40 -0
  3. data/handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md +35 -298
  4. data/handbook/workflow-instructions/overseer/lab-start.wf.md +69 -102
  5. data/handbook/workflow-instructions/overseer/queue.wf.md +39 -219
  6. data/handbook/workflow-instructions/overseer/start.wf.md +66 -240
  7. data/lib/ace/overseer/atoms/report_interpretation.rb +3 -0
  8. data/lib/ace/overseer/atoms/start_contract.rb +2 -2
  9. data/lib/ace/overseer/cli/commands/handoff.rb +15 -3
  10. data/lib/ace/overseer/cli/commands/process_reports.rb +33 -4
  11. data/lib/ace/overseer/cli/commands/start.rb +6 -1
  12. data/lib/ace/overseer/cli/commands/status.rb +1 -1
  13. data/lib/ace/overseer/cli/commands/work_on.rb +15 -3
  14. data/lib/ace/overseer/molecules/coworker_launcher.rb +236 -15
  15. data/lib/ace/overseer/molecules/event_observation.rb +4 -0
  16. data/lib/ace/overseer/molecules/eyes_configuration.rb +26 -0
  17. data/lib/ace/overseer/molecules/eyes_evidence.rb +6 -2
  18. data/lib/ace/overseer/molecules/eyes_readiness.rb +6 -1
  19. data/lib/ace/overseer/molecules/eyes_session_evidence.rb +2 -2
  20. data/lib/ace/overseer/molecules/handoff_probe.rb +2 -1
  21. data/lib/ace/overseer/molecules/hitl_inbox.rb +18 -5
  22. data/lib/ace/overseer/molecules/local_sources.rb +32 -6
  23. data/lib/ace/overseer/molecules/manager_binding.rb +138 -0
  24. data/lib/ace/overseer/molecules/project_observations.rb +19 -43
  25. data/lib/ace/overseer/molecules/project_sessions.rb +59 -6
  26. data/lib/ace/overseer/molecules/report_completion_check.rb +11 -3
  27. data/lib/ace/overseer/molecules/session_environment.rb +3 -8
  28. data/lib/ace/overseer/molecules/worktree_provisioner.rb +2 -2
  29. data/lib/ace/overseer/organisms/handoff_orchestrator.rb +43 -1
  30. data/lib/ace/overseer/organisms/report_processor.rb +145 -17
  31. data/lib/ace/overseer/organisms/start_orchestrator.rb +30 -8
  32. data/lib/ace/overseer/organisms/status_attention.rb +27 -3
  33. data/lib/ace/overseer/organisms/status_collector.rb +22 -2
  34. data/lib/ace/overseer/organisms/work_on_orchestrator.rb +33 -7
  35. data/lib/ace/overseer/version.rb +1 -1
  36. metadata +22 -20
@@ -1,4 +1,5 @@
1
1
  # frozen_string_literal: true
2
+ require "json"
2
3
 
3
4
  module Ace
4
5
  module Overseer
@@ -10,6 +11,8 @@ module Ace
10
11
  desc "Hand the task worktree to the next role in the sequence"
11
12
 
12
13
  option :task, aliases: ["-t"], desc: "Task reference whose worktree receives the next role"
14
+ option :json, type: :boolean, default: false, desc: "Machine result; progress on stderr"
15
+ option :manager, desc: "Private managing task reference"
13
16
  option :runtime, desc: "Terminal backend (auto, tmux, herdr)"
14
17
  option :dry_run, type: :boolean, default: false, desc: "Check handoff readiness without effects"
15
18
  option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
@@ -21,7 +24,7 @@ module Ace
21
24
  @config = config
22
25
  end
23
26
 
24
- def call(task: nil, runtime: nil, dry_run: false, **options)
27
+ def call(task: nil, runtime: nil, dry_run: false, manager: nil, json: false, **options)
25
28
  selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
26
29
  unless %w[auto tmux herdr].include?(selected_runtime)
27
30
  raise Ace::Support::Cli::Error, "unsupported runtime: #{selected_runtime}"
@@ -34,14 +37,23 @@ module Ace
34
37
  raise Ace::Support::Cli::Error.new("--task is required. Usage: ace-overseer handoff --task <ref>")
35
38
  end
36
39
 
37
- progress = options[:quiet] ? nil : ->(msg) { puts msg }
40
+ progress = options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
38
41
  result = @orchestrator.call(
39
42
  task_ref: task_ref,
40
43
  dry_run: dry_run,
41
44
  on_progress: progress,
42
- runtime: selected_runtime
45
+ runtime: selected_runtime, **(manager ? {manager_ref: manager} : {})
43
46
  )
44
47
 
48
+ execution = result[:execution]
49
+ result[:operation] = {
50
+ completed: ["delegation prepared"], running: execution ? [execution["agent"]] : [],
51
+ waiting: execution ? ["executor report"] : [], blocked: [],
52
+ evidence: result.slice(:manager_ref, :task_ref, :worktree_path, :assignment_id, :next)}
53
+ if json
54
+ puts JSON.generate(result)
55
+ return
56
+ end
45
57
  return if options[:quiet]
46
58
 
47
59
  if result[:status] == "sequence_complete"
@@ -1,4 +1,5 @@
1
1
  # frozen_string_literal: true
2
+ require "json"
2
3
 
3
4
  module Ace
4
5
  module Overseer
@@ -9,8 +10,9 @@ module Ace
9
10
 
10
11
  desc "Process incoming ace-hitl reports and continue the overseer queue"
11
12
 
13
+ option :json, type: :boolean, default: false, desc: "Machine result on stdout; progress on stderr"
12
14
  option :scope, type: :string, desc: "HITL scope: current or all (default: owner checkout scope)"
13
- option :owner, type: :string, default: "overseer", desc: "Configured HITL recipient, matching the eyes observer"
15
+ option :owner, type: :string, desc: "Configured HITL recipient, matching the eyes observer"
14
16
  option :dry_run, type: :boolean, default: false, desc: "Interpret reports without writes or continuation"
15
17
  option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
16
18
  option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
@@ -20,15 +22,19 @@ module Ace
20
22
  @processor = processor
21
23
  end
22
24
 
23
- def call(dry_run: false, owner: "overseer", scope: nil, **options)
25
+ def call(dry_run: false, owner: nil, scope: nil, json: false, **options)
24
26
  Atoms::RepoGuard.ensure_repo!
25
27
 
26
- processor = @processor || Organisms::ReportProcessor.new(owner: owner, scope: scope)
28
+ processor = @processor || Organisms::ReportProcessor.new(owner: resolve_owner(owner), scope: scope)
27
29
  result = processor.call(
28
30
  dry_run: dry_run,
29
- on_progress: options[:quiet] ? nil : ->(msg) { puts msg }
31
+ on_progress: options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
30
32
  )
31
33
 
34
+ if json
35
+ puts JSON.generate(result)
36
+ return
37
+ end
32
38
  return if options[:quiet]
33
39
 
34
40
  puts
@@ -45,6 +51,29 @@ module Ace
45
51
  rescue => e
46
52
  raise Ace::Support::Cli::Error.new(e.message)
47
53
  end
54
+
55
+ private
56
+
57
+ def resolve_owner(owner)
58
+ return owner unless owner.to_s.strip.empty?
59
+
60
+ config = Ace::Overseer.config
61
+ configured = config["owner"].to_s.strip
62
+ return configured unless configured.empty?
63
+
64
+ scope = config.dig("start", "scope").to_s.strip
65
+ return "lab-overseer" if scope == "lab"
66
+ return "overseer" if scope == "project"
67
+
68
+ if File.file?(".ace-local/overseer/eyes.json")
69
+ data = JSON.parse(File.read(".ace-local/overseer/eyes.json"))
70
+ recipient = data.is_a?(Hash) ? data["recipient"].to_s.strip : ""
71
+ return recipient unless recipient.empty?
72
+ end
73
+ "overseer"
74
+ rescue JSON::ParserError, SystemCallError
75
+ "overseer"
76
+ end
48
77
  end
49
78
  end
50
79
  end
@@ -87,9 +87,14 @@ module Ace
87
87
 
88
88
  role = report["scope"] == "lab" ? "lab-overseer" : "project-overseer"
89
89
  directory = nil
90
- Molecules::SessionEnvironment.new.with_environment(root: report.fetch("root"), role: role) do |path, credentials, _args|
90
+ Molecules::SessionEnvironment.new.with_environment(root: report.fetch("root"), role: role, eyes_config: report["eyes_config"]) do |path, credentials, _args|
91
91
  directory = credentials
92
92
  environment = JSON.parse(File.read(path))
93
+ # Foreground Pi occupies this terminal; delegated launches receive
94
+ # their destination context from native Herdr instead.
95
+ environment.merge!(ENV.to_h.slice("HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"))
96
+ environment["HERDR_PANE"] = environment["HERDR_PANE_ID"] if environment["HERDR_PANE_ID"]
97
+ environment["HERDR_SESSION"] = environment["HERDR_WORKSPACE_ID"] if environment["HERDR_WORKSPACE_ID"]
93
98
  system(environment, *report.fetch("command"), unsetenv_others: true)
94
99
  status = $?
95
100
  unless status&.success?
@@ -25,7 +25,7 @@ module Ace
25
25
 
26
26
  def call(format:, runtime: nil, **options)
27
27
  selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
28
- unless %w[auto tmux].include?(selected_runtime)
28
+ unless %w[auto tmux herdr].include?(selected_runtime)
29
29
  raise Ace::Support::Cli::Error, "unsupported local runtime: #{selected_runtime}"
30
30
  end
31
31
 
@@ -1,4 +1,5 @@
1
1
  # frozen_string_literal: true
2
+ require "json"
2
3
 
3
4
  module Ace
4
5
  module Overseer
@@ -12,6 +13,8 @@ module Ace
12
13
  option :task, aliases: ["-t"], type: :array,
13
14
  desc: "Task reference(s), repeatable and comma-separated (e.g., 230 --task 231,232)"
14
15
  option :preset, aliases: ["-p"], desc: "Assignment preset name"
16
+ option :json, type: :boolean, default: false, desc: "Machine result; progress on stderr"
17
+ option :manager, desc: "Private managing task reference"
15
18
  option :runtime, desc: "Terminal backend (auto, tmux, herdr)"
16
19
  option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
17
20
  option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
@@ -22,7 +25,7 @@ module Ace
22
25
  @config = config
23
26
  end
24
27
 
25
- def call(task: nil, preset: nil, runtime: nil, **options)
28
+ def call(task: nil, preset: nil, runtime: nil, manager: nil, json: false, **options)
26
29
  raise Ace::Support::Cli::Error, "--work is obsolete; select task or preset" if options.key?(:work)
27
30
  selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
28
31
  unless %w[auto tmux herdr].include?(selected_runtime)
@@ -36,14 +39,23 @@ module Ace
36
39
  raise Ace::Support::Cli::Error.new("--task is required. Usage: ace-overseer work-on --task <ref>")
37
40
  end
38
41
 
39
- progress = options[:quiet] ? nil : ->(msg) { puts msg }
42
+ progress = options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
40
43
  result = @orchestrator.call(
41
44
  task_ref: task_refs.first,
42
45
  task_refs: task_refs,
43
46
  cli_preset: preset,
44
- on_progress: progress, runtime: selected_runtime
47
+ on_progress: progress, runtime: selected_runtime, **(manager ? {manager_ref: manager} : {})
45
48
  )
46
49
 
50
+ execution = result[:execution]
51
+ result[:operation] = {
52
+ completed: ["delegation prepared"], running: execution ? [execution["agent"]] : [],
53
+ waiting: execution ? ["executor report"] : [], blocked: [],
54
+ evidence: result.slice(:manager_ref, :task_ref, :worktree_path, :assignment_id, :next)}
55
+ if json
56
+ puts JSON.generate(result)
57
+ return
58
+ end
47
59
  return if options[:quiet]
48
60
 
49
61
  if result[:execution]
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "shellwords"
3
4
  require "ace/coworker/molecules/execution_binding"
4
5
  require "ace/herdr"
5
6
  require "ace/herdr/atoms/native_agent_session"
@@ -12,7 +13,9 @@ module Ace::Overseer::Molecules
12
13
  class CoworkerLauncher
13
14
  def initialize(executor: Ace::Herdr::Molecules::HerdrExecutor.new, env: ENV,
14
15
  environment: nil, bindings: Ace::Coworker::Molecules::ExecutionBinding.new,
15
- brief_factory: nil, readiness: nil, eyes: nil, root_resolver: nil)
16
+ brief_factory: nil, readiness: nil, eyes: nil, root_resolver: nil,
17
+ identity_timeout: 10, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, sleeper: ->(seconds) { sleep(seconds) })
18
+ @identity_timeout, @clock, @sleeper = identity_timeout, clock, sleeper
16
19
  @executor, @env, @bindings = executor, env, bindings
17
20
  @environment = environment || SessionEnvironment.new(env: env)
18
21
  @brief_factory = brief_factory || ->(root, path) { Ace::Coworker::Organisms::StartOrchestrator.new(project_root: root).call(config_path: path) }
@@ -48,7 +51,18 @@ module Ace::Overseer::Molecules
48
51
  raise Ace::Overseer::Error, "executor commission changed during validation"
49
52
  end
50
53
  if document["execution"]
51
- next reuse(document.fetch("execution"))
54
+ execution = document.fetch("execution")
55
+ if %w[resuming resumed].include?(execution["state"])
56
+ next finish_resume(execution, brief, worktree_path, save)
57
+ end
58
+ if %w[launching started].include?(execution["state"])
59
+ unless %w[paused empty].include?(brief.assignment_snapshot&.state.to_s)
60
+ raise Ace::Overseer::Error, "unconfirmed executor already has assignment activity"
61
+ end
62
+ recover_unprompted(execution, worktree_path, save)
63
+ next submit_prompt(execution, brief, save)
64
+ end
65
+ next reuse(execution, brief, worktree_path, save)
52
66
  end
53
67
  unless %w[paused empty].include?(brief.assignment_snapshot&.state.to_s)
54
68
  raise Ace::Overseer::Error, "unbound assignment is not ready for a new executor"
@@ -72,20 +86,14 @@ module Ace::Overseer::Molecules
72
86
  result = dispatcher.dispatch(label: name, prompt: "", kind: "pi", cwd: worktree_path,
73
87
  env_file: file, args: Array(profile_args) + ["--append-system-prompt", brief.instructions_source])
74
88
  execution.merge!(result.to_h).merge!("state" => "started")
89
+ save.call # Preserve the native receipt before asynchronous session publication.
75
90
  pane = pane_identity(execution.fetch("pane"))
76
91
  execution["terminal_id"] = pane.fetch("terminal_id")
77
- execution["agent_session"] = session_identity(pane)
92
+ save.call
93
+ execution["agent_session"] = await_session(execution)
78
94
  save.call
79
95
  end
80
- # Record uncertainty BEFORE submission. A crash after input reaches Pi
81
- # cannot cause the same task to be submitted again automatically.
82
- execution["state"] = "prompting"
83
- save.call
84
- prompt = "#{brief.config.start_prompt}\n\n#{Ace::Coworker::Atoms::BriefFormatter.format_table(brief)}"
85
- @executor.agent_prompt(pane: execution.fetch("pane"), text: prompt)
86
- execution["state"] = "running"
87
- save.call
88
- execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => false)
96
+ submit_prompt(execution, brief, save)
89
97
  end
90
98
  rescue Ace::Coworker::Error, Ace::Herdr::ExecutorError => e
91
99
  raise Ace::Overseer::Error, "executor launch blocked: #{e.message}"
@@ -120,7 +128,66 @@ module Ace::Overseer::Molecules
120
128
 
121
129
  private
122
130
 
123
- def reuse(execution)
131
+ def submit_prompt(execution, brief, save)
132
+ # A crash after input reaches Pi must never repeat the commission.
133
+ execution["state"] = "prompting"
134
+ save.call
135
+ prompt = "#{brief.config.start_prompt}\n\n#{Ace::Coworker::Atoms::BriefFormatter.format_table(brief)}"
136
+ @executor.agent_prompt(pane: execution.fetch("pane"), text: prompt)
137
+ execution["state"] = "running"
138
+ save.call
139
+ execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => false)
140
+ end
141
+
142
+ def await_session(execution)
143
+ deadline = @clock.call + @identity_timeout
144
+ loop do
145
+ pane = pane_identity(execution.fetch("pane"))
146
+ unless pane["terminal_id"] == execution.fetch("terminal_id")
147
+ raise Ace::Overseer::Error, "executor terminal changed before session publication"
148
+ end
149
+ identity = Ace::Herdr::Atoms::NativeAgentSession.normalize(pane["agent_session"], agent: "pi")
150
+ if identity
151
+ raw = pane["agent_session"]
152
+ execution["session_path"] = raw["value"] if raw.is_a?(Hash) && raw["kind"] == "path"
153
+ return identity
154
+ end
155
+ raise Ace::Overseer::Error, "native executor session identity is unavailable; retry the same handoff" if @clock.call >= deadline
156
+ @sleeper.call(0.2)
157
+ end
158
+ end
159
+
160
+ def recover_unprompted(execution, worktree_path, save)
161
+ row = @executor.agent_get(execution["pane"] || execution.fetch("agent")).parsed_json&.dig("result", "agent")
162
+ unless row.is_a?(Hash) && row["name"] == execution["agent"] &&
163
+ row["cwd"] == worktree_path && row["agent_status"] == "idle" &&
164
+ row["interactive_ready"] == true && row["pane_id"] && row["terminal_id"]
165
+ raise Ace::Overseer::Error, "unconfirmed launch is not the expected idle executor"
166
+ end
167
+ if execution["terminal_id"] && execution["terminal_id"] != row["terminal_id"]
168
+ raise Ace::Overseer::Error, "executor terminal changed before recovery"
169
+ end
170
+ identity = session_identity(row)
171
+ if execution["agent_session"] && execution["agent_session"] != identity
172
+ raise Ace::Overseer::Error, "executor session changed before recovery"
173
+ end
174
+ # Without a saved Pi identity, bind only the unique private session
175
+ # directory allocated for this dispatch, never an arbitrary same-name pane.
176
+ unless execution["agent_session"]
177
+ directory = execution["credentials_directory"]
178
+ native_session = row.fetch("agent_session")
179
+ unless directory && native_session["kind"] == "path" && native_session["value"].start_with?("#{directory}/sessions/")
180
+ raise Ace::Overseer::Error, "unconfirmed launch has no matching session provenance"
181
+ end
182
+ end
183
+ execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"],
184
+ "agent_session" => identity, "state" => "started")
185
+ raw = row["agent_session"]
186
+ execution["session_path"] = raw["value"] if raw.is_a?(Hash) && raw["kind"] == "path"
187
+ save.call
188
+ end
189
+
190
+ def reuse(execution, brief, worktree_path, save)
124
191
  if execution["state"] == "retired"
125
192
  raise Ace::Overseer::Error, "recorded executor is retired; reconcile the assignment before starting another"
126
193
  end
@@ -128,16 +195,170 @@ module Ace::Overseer::Molecules
128
195
  raise Ace::Overseer::Error, "executor start is unconfirmed; inspect the recorded assignment before retrying"
129
196
  end
130
197
  pane = pane_identity(execution.fetch("pane"))
131
- unless same_executor?(pane, execution)
198
+ unless pane["terminal_id"] == execution["terminal_id"]
132
199
  raise Ace::Overseer::Error, "recorded executor terminal no longer matches"
133
200
  end
134
- agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
201
+ begin
202
+ agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
203
+ rescue Ace::Herdr::AgentNotFoundError
204
+ return resume_dead(execution, brief, worktree_path, pane, save)
205
+ end
135
206
  unless agent.is_a?(Hash) && agent["interactive_ready"] == true && same_executor?(agent, execution)
136
207
  raise Ace::Overseer::Error, "recorded executor is not a live interactive agent"
137
208
  end
138
209
  execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => true)
139
210
  end
140
211
 
212
+ def resume_dead(execution, brief, worktree_path, pane, save)
213
+ unless brief.assignment_snapshot&.state.to_s == "running" && pane["cwd"] == worktree_path
214
+ raise Ace::Overseer::Error, "dead executor recovery requires its running assignment and original directory"
215
+ end
216
+ transcript = resume_transcript(execution, worktree_path)
217
+ SessionEnvironment.cleanup(execution["credentials_directory"])
218
+ @environment.with_environment(root: worktree_path, role: brief.config.role) do |file, directory, args|
219
+ execution.merge!("state" => "resuming", "resume_transcript" => transcript,
220
+ "credentials_directory" => directory)
221
+ save.call # An uncertain native start must be inspected, never repeated.
222
+ @executor.agent_start(name: execution.fetch("agent"), kind: "pi", pane: execution.fetch("pane"),
223
+ timeout_ms: 60_000, env_file: file,
224
+ args: Array(args) + ["--session", transcript, "--append-system-prompt", brief.instructions_source])
225
+ identity = await_session(execution)
226
+ raise Ace::Overseer::Error, "resumed executor session changed" unless identity == execution["agent_session"]
227
+ execution["state"] = "resumed"
228
+ save.call
229
+ end
230
+ finish_resume(execution, brief, worktree_path, save)
231
+ end
232
+
233
+ def finish_resume(execution, brief, worktree_path, save)
234
+ raise Ace::Overseer::Error, "resumed assignment is no longer running" unless brief.assignment_snapshot&.state.to_s == "running"
235
+ if execution["replacement_pending"]
236
+ recover_replacement(execution, worktree_path, save)
237
+ end
238
+ begin
239
+ agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
240
+ rescue Ace::Herdr::AgentNotFoundError
241
+ raise unless execution["state"] == "resuming"
242
+ pane = pane_identity(execution.fetch("pane"))
243
+ if pane["terminal_id"] != execution["terminal_id"]
244
+ return replace_resume_terminal(execution, brief, worktree_path, pane, save)
245
+ end
246
+ pane = confirmed_resume_shell(execution, worktree_path)
247
+ return resume_dead(execution, brief, worktree_path, pane, save)
248
+ end
249
+ unless agent.is_a?(Hash) && same_executor?(agent, execution) && agent["cwd"] == worktree_path &&
250
+ agent["name"] == execution["agent"] && agent["interactive_ready"] == true && %w[idle done].include?(agent["agent_status"])
251
+ raise Ace::Overseer::Error, "resumed executor is not the expected idle session; inspect before retrying"
252
+ end
253
+ execution["state"] = "resume_prompting"
254
+ save.call
255
+ @executor.agent_prompt(pane: execution.fetch("pane"), text:
256
+ "Continue the existing assignment #{brief.config.assignment} after process interruption. " \
257
+ "Read its current owner state and preserved reports; resume unfinished work only. " \
258
+ "Do not repeat completed effects or create a replacement assignment. " \
259
+ "Use ace-coworker resume --config #{Shellwords.escape(brief.config.source_path)} to assess continuation.")
260
+ execution["state"] = "running"
261
+ save.call
262
+ execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => true, "resumed" => true)
263
+ end
264
+
265
+ def resume_inventory
266
+ rows = @executor.agent_list.parsed_json&.dig("result", "agents")
267
+ unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row["name"].is_a?(String) && row["pane_id"].is_a?(String) &&
268
+ Ace::Herdr::Atoms::NativeAgentSession.normalize(row["agent_session"], agent: row["agent"]) }
269
+ raise Ace::Overseer::Error, "native executor inventory is incomplete"
270
+ end
271
+ rows
272
+ end
273
+
274
+ def replacement_matches(execution)
275
+ resume_inventory.select do |row|
276
+ row["name"] == execution["agent"] ||
277
+ Ace::Herdr::Atoms::NativeAgentSession.normalize(row["agent_session"], agent: "pi") == execution["agent_session"]
278
+ end
279
+ end
280
+
281
+ def recover_replacement(execution, worktree_path, save)
282
+ rows = replacement_matches(execution)
283
+ row = rows.one? && rows.first
284
+ unless row && row["name"] == execution["agent"] && row["cwd"] == worktree_path && row["terminal_id"] &&
285
+ row["interactive_ready"] == true && %w[idle done].include?(row["agent_status"]) && session_identity(row) == execution["agent_session"]
286
+ raise Ace::Overseer::Error, "replacement resume is unconfirmed; inspect before retrying"
287
+ end
288
+ execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"])
289
+ execution.delete("replacement_pending")
290
+ save.call
291
+ end
292
+
293
+ def replace_resume_terminal(execution, brief, worktree_path, pane, save)
294
+ transcript = resume_transcript(execution, worktree_path)
295
+ info = @executor.pane_process_info(execution.fetch("pane")).parsed_json&.dig("result", "process_info")
296
+ unless pane["cwd"] == worktree_path && shell_only?(info, execution["pane"]) && replacement_matches(execution).empty?
297
+ raise Ace::Overseer::Error, "old executor absence is unconfirmed; replacement refused"
298
+ end
299
+ # A native live handoff may replace terminal identity. Never send input
300
+ # to or close that old pane; resume the same Pi transcript in a new pane.
301
+ SessionEnvironment.cleanup(execution["credentials_directory"])
302
+ @environment.with_environment(root: worktree_path, role: brief.config.role) do |file, directory, args|
303
+ execution["previous_terminal"] = execution.slice("pane", "terminal_id")
304
+ execution.merge!("replacement_pending" => true, "credentials_directory" => directory, "resume_transcript" => transcript)
305
+ save.call
306
+ dispatcher = Ace::Herdr::Organisms::Dispatcher.from_config(executor: @executor)
307
+ result = dispatcher.dispatch(label: execution.fetch("agent"), prompt: "", kind: "pi", cwd: worktree_path,
308
+ workspace_id: execution["workspace"], env_file: file,
309
+ args: Array(args) + ["--session", transcript, "--append-system-prompt", brief.instructions_source])
310
+ execution.merge!(result.to_h)
311
+ execution["terminal_id"] = pane_identity(execution.fetch("pane")).fetch("terminal_id")
312
+ save.call
313
+ identity = await_session(execution)
314
+ raise Ace::Overseer::Error, "replacement executor session changed" unless identity == execution["agent_session"]
315
+ execution.delete("replacement_pending")
316
+ save.call
317
+ end
318
+ finish_resume(execution, brief, worktree_path, save)
319
+ end
320
+
321
+ def shell_only?(info, pane)
322
+ info.is_a?(Hash) && info["pane_id"] == pane && info["shell_pid"].is_a?(Integer) && info["shell_pid"].positive? &&
323
+ info["foreground_process_group_id"] == info["shell_pid"] && info["foreground_processes"].is_a?(Array) &&
324
+ info["foreground_processes"].length == 1 && info["foreground_processes"].first.is_a?(Hash) &&
325
+ info["foreground_processes"].first["pid"] == info["shell_pid"]
326
+ end
327
+
328
+ def confirmed_resume_shell(execution, worktree_path)
329
+ pane = pane_identity(execution.fetch("pane"))
330
+ info = @executor.pane_process_info(execution.fetch("pane")).parsed_json&.dig("result", "process_info")
331
+ unless info.is_a?(Hash) && pane["terminal_id"] == execution["terminal_id"] && pane["cwd"] == worktree_path &&
332
+ info["pane_id"] == execution["pane"] && info.dig("guarded_prompt_origin", "terminal_id") == execution["terminal_id"] &&
333
+ info["guarded_prompt"] == true && info["guarded_input_drain"] == true &&
334
+ shell_only?(info, execution["pane"])
335
+ raise Ace::Overseer::Error, "failed resume has no confirmed original shell; inspect before retrying"
336
+ end
337
+ pane
338
+ end
339
+
340
+ def resume_transcript(execution, worktree_path)
341
+ candidates = if execution["resume_transcript"]
342
+ [execution.fetch("resume_transcript")]
343
+ else
344
+ directory = execution["credentials_directory"]
345
+ raise Ace::Overseer::Error, "executor has no private session directory" unless directory
346
+ Dir.glob(File.join(directory, "sessions", "**", "*.jsonl")).select do |path|
347
+ Ace::Herdr::Atoms::NativeAgentSession.normalize({"agent" => "pi", "kind" => "path", "value" => path}, agent: "pi") == execution["agent_session"]
348
+ end
349
+ end
350
+ raise Ace::Overseer::Error, "executor transcript is missing or ambiguous" unless candidates.length == 1
351
+ path = candidates.first
352
+ raise Ace::Overseer::Error, "executor transcript is not a regular file" unless File.file?(path) && !File.symlink?(path)
353
+ header = File.open(path) { |file| JSON.parse(file.readline) }
354
+ unless header["type"] == "session" && header["id"] == execution.dig("agent_session", "value") && header["cwd"] == worktree_path
355
+ raise Ace::Overseer::Error, "executor transcript identity does not match"
356
+ end
357
+ path
358
+ rescue JSON::ParserError, EOFError, SystemCallError
359
+ raise Ace::Overseer::Error, "executor transcript is unavailable or invalid"
360
+ end
361
+
141
362
  def pane_identity(pane)
142
363
  reply = @executor.pane_get(pane).parsed_json
143
364
  row = reply&.dig("result", "pane")
@@ -76,6 +76,10 @@ module Ace
76
76
  verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: managers)
77
77
  next false unless verdict[:status] == :duplicate
78
78
  manager = managers.find { |task| task.id.to_s == verdict[:manager_ref] }
79
+ step = Array(manager&.subtasks).find { |candidate| candidate.id.to_s == verdict[:step_ref] } || manager
80
+ receipt = step&.metadata&.fetch("report_receipt", nil)
81
+ next false unless receipt.is_a?(Hash) && receipt["key"] == event["key"] &&
82
+ receipt["revision"] == event["revision"] && receipt["cleanup"] == "complete" && receipt["continuation"] == "complete"
79
83
  # A persisted report alone is not proof its continuation ran. Keep
80
84
  # active managers eligible after restart; their existing gates reconcile
81
85
  # the same attempt. Only completed trees suppress historical reports.
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+ require "json"
3
+ require "fileutils"
4
+ require "tempfile"
5
+
6
+ module Ace::Overseer::Molecules
7
+ # Start owns the standard session input; Pi owns observation checkpoints.
8
+ class EyesConfiguration
9
+ def self.prepare(root:, recipient:)
10
+ path = File.join(root, ".ace-local/overseer/eyes.json")
11
+ existing = File.file?(path) ? JSON.parse(File.read(path)) : {}
12
+ raise Ace::Overseer::Error, "eyes configuration must be an object" unless existing.is_a?(Hash)
13
+ config = existing.merge("scope" => "all", "recipient" => recipient)
14
+ FileUtils.mkdir_p(File.dirname(path))
15
+ Tempfile.create(["eyes-", ".json"], File.dirname(path)) do |file|
16
+ file.write(JSON.pretty_generate(config) + "\n")
17
+ file.flush
18
+ file.fsync
19
+ File.rename(file.path, path)
20
+ end
21
+ path
22
+ rescue JSON::ParserError, SystemCallError => error
23
+ raise Ace::Overseer::Error, "cannot prepare eyes configuration: #{error.message}"
24
+ end
25
+ end
26
+ end
@@ -12,7 +12,7 @@ module Ace
12
12
  BINDING = "ace-wake-eyes-binding"
13
13
  BIRTH = /\A(?:linux:[0-9a-f-]{36}:[1-9][0-9]*|darwin:[1-9][0-9]*:[0-9]{1,6})\z/
14
14
 
15
- def self.ready?(branch:, root:, process:, prompt:, required_sources:, now_ms:)
15
+ def self.ready?(branch:, root:, process:, prompt:, required_sources:, now_ms:, expected_config: nil)
16
16
  return false unless branch.is_a?(Array) && root.is_a?(String) && process.is_a?(Hash) &&
17
17
  prompt.is_a?(String) && !prompt.empty? && required_sources.is_a?(Array) &&
18
18
  !required_sources.empty? && required_sources.all? { |name| name.is_a?(String) && !name.empty? } &&
@@ -20,6 +20,10 @@ module Ace
20
20
  process["started_at"].match?(BIRTH) && now_ms.is_a?(Integer)
21
21
  eye_index = branch.rindex { |entry| entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == ENTRY }
22
22
  return false unless eye_index
23
+ if expected_config
24
+ actual = branch[eye_index].dig("data", "config")
25
+ return false unless actual.is_a?(Hash) && expected_config.all? { |key, value| actual[key] == value }
26
+ end
23
27
 
24
28
  identity = {"pid" => process["pid"], "startedAt" => process["started_at"]}
25
29
 
@@ -86,7 +90,7 @@ module Ace
86
90
  evidence = eye["observerEvidence"]
87
91
  return false unless evidence.is_a?(Hash) && evidence["process"] == identity
88
92
  observed, sources, config = evidence.values_at("observedAt", "sources") + [eye["config"]]
89
- return false unless observed.is_a?(Integer) && observed >= prompt_at && observed <= now_ms && config.is_a?(Hash) &&
93
+ return false unless observed.is_a?(Integer) && observed <= now_ms && config.is_a?(Hash) &&
90
94
  config["intervalSeconds"].is_a?(Integer) && config["intervalSeconds"].between?(1, 3600) &&
91
95
  config["maxObservationsPerHour"].is_a?(Integer) && config["maxObservationsPerHour"].between?(1, 3600) &&
92
96
  config["timeoutMs"].is_a?(Integer) && config["timeoutMs"].between?(100, 120_000)
@@ -13,7 +13,12 @@ module Ace
13
13
  end
14
14
 
15
15
  def ready?(pane:, root:, prompt:, required_sources:)
16
- @local.ready?(pane: pane, root: root, prompt: prompt, required_sources: required_sources)
16
+ path = File.join(root, ".ace-local/overseer/eyes.json")
17
+ expected = JSON.parse(File.read(path))
18
+ return false unless expected.is_a?(Hash) && expected["scope"] == "all" && !expected["recipient"].to_s.empty?
19
+ @local.ready?(expected_config: expected.slice("scope", "recipient"), pane: pane, root: root, prompt: prompt, required_sources: required_sources)
20
+ rescue SystemCallError, JSON::ParserError
21
+ false
17
22
  end
18
23
  end
19
24
  end
@@ -46,7 +46,7 @@ module Ace
46
46
  @executor, @identity, @clock, @file_opener = executor, identity, clock, file_opener
47
47
  end
48
48
 
49
- def ready?(pane:, root:, prompt:, required_sources:, expected_terminal: nil)
49
+ def ready?(pane:, root:, prompt:, required_sources:, expected_terminal: nil, expected_config: nil)
50
50
  executor = @executor || Ace::Herdr::Molecules::BoundedObservation.new(
51
51
  deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5)
52
52
  before = pane_binding(executor, pane)
@@ -68,7 +68,7 @@ module Ace
68
68
  process = @identity.capture(pid)
69
69
  return false unless process && process["uid"] == stat.uid
70
70
  return false unless EyesEvidence.ready?(branch: branch, root: root, process: process,
71
- prompt: prompt, required_sources: required_sources, now_ms: @clock.call)
71
+ prompt: prompt, required_sources: required_sources, expected_config: expected_config, now_ms: @clock.call)
72
72
  # The owner or its session may change while the file is read.
73
73
  return false unless @identity.capture(pid) == process && foreground?(executor, pane, pid) && pane_binding(executor, pane) == before
74
74
  final = file.stat
@@ -43,6 +43,7 @@ module Ace
43
43
  {
44
44
  "role" => mapping["role"],
45
45
  "start_config" => mapping["start_config"],
46
+ "execution" => mapping["execution"],
46
47
  "assignment" => record["id"],
47
48
  "name" => record["name"],
48
49
  "state" => states.fetch(record["id"], "")
@@ -91,7 +92,7 @@ module Ace
91
92
  role = data["role"].to_s
92
93
  next if assignment.empty? || role.strip.empty?
93
94
 
94
- [assignment, {"role" => role,
95
+ [assignment, {"role" => role, "execution" => data["execution"],
95
96
  "start_config" => File.join(PREPARE_DIR, File.basename(path))}]
96
97
  end.to_h
97
98
  end