ace-overseer 0.28.0 → 0.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0228801ebed27e7b1fca7fe8f580dc4fdc2a5a5be9e8d76d3c6cf59b1f8cf48
-  data.tar.gz: 2fae06ba1fc9174fc41f53f3ddcbcc1ee8dddd0152faaaa7e894a862d6f0e8c5
+  metadata.gz: 4d96c79ae10f470e6358022f081234f5080eba56cd58353471a33aa6f187e0c5
+  data.tar.gz: 5e4eadc41222d3448b57f938ad5c2716b1941ddfe7b800479d69a6a3f72f3cb9
 SHA512:
-  metadata.gz: 2ede68b20a4104eeb494014ca34a05627e8367aa5d1b6cf71cbd5f8fcfa0e4168e2029c3ca78be121e353e3e24a25bc0dd0c5ae153850b9797a7bff5bf504e6c
-  data.tar.gz: 611af27c6c2b7febc096cefeaff5545d8f3ce7fd1dd9e377932371359c850ec0e1f757476d9ffba937135f3ea021bd87f4c268007ab81b0e571c1723b48c4d88
+  metadata.gz: f9fdda6024283fd16b8be35da318b7e4eb6a85574ef623cc1395c4c7af0d77fc1971a541bb2a28abe3a6ce7a6d52f1c04df442c69eaff53e09f7d3974b6b89e3
+  data.tar.gz: 4fe70abfe425a0c399763c790125f391bbca8099f5a96e4a24677047148fc4b7e1c578ae976853195a28f1e5306500e259de498a491601e241e1c82e1b514c91

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.1] - 2026-10-31
+
+### Fixed
+
+- Transfer terminal runtime setup through a private script and require its
+  acknowledgement before launch, preventing canonical-input PATH truncation.
+
+- Bind unassigned readiness only to explicit planner allocations; reject missing
+  report identities and conflicting task/role references. Persist bootstrap
+  assignment and receipt identities in task metadata, using resolved task paths.
+  Check real completed assignment and role ownership before accepting success;
+  leave confirm-start continuation to the coordinator without worker dispatch.
+
+- Preserve concrete child startup failures reported before project scope is
+  established, while continuing to reject unscoped or wrong-scope success.
+
+- Delegate bootstrap diagnosis and reproduction to workers as well as repair;
+  a known symptom is enough to commission work. Reconcile project startup only
+  after accepted worker completion and independent verification.
+
 ## [0.28.0] - 2026-10-31
 
 ### Fixed

data/handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md

@@ -10,6 +10,16 @@ purpose: Complete one lab-owned startup commission without the overseer doing th
 
 ## Commission and ownership
 
+The overseer reads owner state and public CLI contracts to establish scope,
+existing execution and the observed symptom. Technical diagnosis, source-code
+investigation, troubleshooting and reproduction commands belong to the worker.
+Record the known failure and desired outcome in the commission; discovering
+the root cause is part of the assigned work, never a prerequisite for dispatch.
+Use existing readiness state, or a startup dry run only when that state is
+otherwise unknown. Do not turn that check into a technical investigation.
+Once the symptom is known, proceed to task creation/reconciliation, observation
+and worker dispatch, then end the turn.
+
 Read existing tasks and assignments first. Reuse the open commission for the
 same project and goal; unknown execution state never means free capacity.
 Create one lab coordination task in `_overseer`, with three direct children:
@@ -19,9 +29,12 @@ predecessor. Only the lab overseer updates this private tree.
 Create a separate executable lab task through `ace-task` for the bootstrap
 work, linking it as the manager's `project_task`. Keep its specification in
 its task folder. Include the canonical target repository path, required
-configuration, allowed changes, runtime mode, acceptance checks and report
-recipient. This is lab infrastructure work, not a project product task.
-Workers must not edit the private coordination tree.
+configuration, observed failure, desired outcome, allowed changes, runtime
+mode, acceptance checks and report recipient. Assign diagnosis and reproduction
+as well as preparation to the worker. This is lab infrastructure work, not a project product task.
+Workers must not edit the private coordination tree. Resolve each task folder
+from `ace-task show <ref>` before writing commission, dispatch or receipt notes;
+never construct a folder from a guessed or expanded title slug.
 
 Explicit `ACE_TOOLCHAIN=installed` remains installed in every subprocess,
 worker and resumed session. The project checkout is domain data. Never modify
@@ -44,7 +57,19 @@ report that capability gap. Do not claim that mentioning `/eyes` armed it.
 Use `ace-coworker prepare --task <executable-task> --roles bootstrap-worker,bootstrap-verifier
 --to <configured-overseer-address> --format json`. Read its returned worktree,
 assignment IDs and start-config paths; record these on the matching private
-steps before launch. A preparation readiness report is not worker completion.
+steps before launch through the task API, not only in prose:
+
+```bash
+ace-task update <prepare-step> --set assignment=<worker-assignment> --set role=bootstrap-worker --set worktree=<returned-worktree>
+ace-task update <verify-step> --set assignment=<verifier-assignment> --set role=bootstrap-verifier --set worktree=<returned-worktree>
+ace-task update <confirm-step> --set role=confirm-start
+```
+
+Read back the steps with `ace-task show` and verify exact returned identities.
+A preparation readiness report is not worker completion. It does not complete
+any of these three steps; never label bootstrap execution as `role=planner`.
+Only a separate, explicitly commissioned planner preparation allocation may
+accept an unassigned readiness report.
 The task must be present in the execution worktree before any agent starts.
 
 `ace-coworker start --config <returned-path>` validates and prints a brief;
@@ -68,7 +93,13 @@ report ID, task, assignment and role; a preparation report, process exit or
 unmatched message is not success. Use `ace-overseer process-reports --dry-run`
 to inspect the matching and continuation before applying it. Only accept
 worker success with a completed non-empty assignment and the promised evidence.
-Record receipt through task APIs before acknowledging the eyes revision.
+Record the actual accepted HITL event ID and result in step metadata through
+`ace-task update <step> --set processed_report=<event-id> --set report_result=<result>`
+(or let `process-reports` perform that same write after its dry run is checked).
+Mark done only after acceptance; errors keep the step open. Receipt notes in
+the path returned by `ace-task show` supplement these fields, never replace them.
+Read back the recorded identity before acknowledging the eyes revision.
+Never put a preparation readiness ID on a worker, verifier or confirm-start step.
 
 Use the existing role handoff gate to prepare the independent reviewer after
 worker completion. As with the worker, a printed start command is not a live
@@ -77,8 +108,8 @@ confirm first-turn delivery. Do not launch a second executor while an earlier
 one is active or its state is unknown. On repeated delivery, reconcile existing
 assignments and agents instead of dispatching again.
 
-After accepted independent verification, the overseer performs its coordination
-operation `ace-overseer start --reconcile`. Confirm the target's session, first
+Only after accepted worker completion and independent verification does the
+overseer perform this commission's project-start coordination operation `ace-overseer start --reconcile`. Confirm the target's session, first
 turn and active eyes from actual session evidence. A ready process alone is
 not initialized observation. Close the confirmation step and managing task
 only with these proofs; the worker report alone cannot close the family.

data/handbook/workflow-instructions/overseer/lab-start.wf.md

@@ -21,8 +21,12 @@ the right project. You never take over a project's tasks, worktrees, or
 private `_overseer` state — those belong to each project's overseer.
 
 You own the OUTCOME of routine startup, never its execution. Configuration,
-Bundler installation, dependency repairs and binstub generation are WORKER
-work. Create a commission and dispatch a separate lab worker even when the
+Bundler installation, dependency repairs, binstub generation and technical
+diagnosis are WORKER work. Read owner state and public CLI contracts to route
+the commission; source-code investigation, troubleshooting and reproduction
+commands belong to the worker. Capture the observed symptom and desired
+outcome. An unknown root cause is not a reason to postpone task creation and
+dispatch. Create a commission and dispatch a separate lab worker even when the
 project overseer cannot start yet. Do not edit project configuration, install
 packages or run repair commands yourself. Missing workers are a concrete
 capability gap, not a reason to become the worker.
@@ -37,8 +41,8 @@ for the Captain to write YAML. The packaged bootstrap profile is
 and an invalid explicit configuration never silently falls back.
 
 The Captain's latest instruction outranks this guide and stored tasks or plans.
-On this first turn, establish your own configuration and the commissioned
-project overseers before resuming unrelated stored backlog. Read old
+On this first turn, commission any missing configuration and project
+preparation through workers before resuming unrelated stored backlog. Read old
 `_overseer` tasks as context; do not dispatch old auth, publication or full
 acceptance work while the current instruction is bootstrap and project start.
 Report scope conflicts to the host operator instead of negotiating away a new
@@ -53,10 +57,14 @@ Captain order.
    eyes configuration path. Check enabled=true, breaker=null, errors=0 and
    a successful observation before dispatch. A missing tool/configuration is
    a readiness gap. Writing `/eyes` in prose does not arm observation.
-4. Use `ace-overseer start --reconcile` to inspect/start commissioned project
-   sessions. Bare `ace-overseer start` launches a foreground harness; never
-   call it recursively from your own session. Delegate preparation or repair
-   of blocked projects to a lab worker through the bootstrap procedure.
+4. For a preparation commission, read existing readiness/session state; use
+   a startup dry run only if needed to establish an otherwise unknown status.
+   Do not investigate its implementation or reproduce the failure yourself.
+   Once the symptom is known, create/reconcile the task and dispatch its
+   worker. Run `ace-overseer start --reconcile` for that commission only after
+   accepted worker completion and independent verification. Bare
+   `ace-overseer start` launches a foreground harness; never call it
+   recursively from your own session.
 5. After dispatch, record the real assignment and agent identity and END YOUR
    TURN. Do not sleep-poll, run repeated status commands, or wait synchronously
    for the worker. A semantic change wakes you; unchanged state stays silent.

data/handbook/workflow-instructions/overseer/queue.wf.md

@@ -80,6 +80,7 @@ task:
 ```bash
 ace-task create "Manage: <scope>" --in _overseer --tags queue
 ace-task create "Prepare <scope>" --child-of <manager-ref>
+ace-task update <prep-ref> --set role=planner
 ace-task create "Implement <scope>" --child-of <manager-ref>
 ace-task create "Review <scope>" --child-of <manager-ref>
 ace-task create "Integrate <scope>" --child-of <manager-ref>
@@ -94,7 +95,11 @@ Rules:
 - Add worktree/assignment references only after they really exist (the
   planner prepares them); never fabricate references ahead of preparation.
   Record them on the step that owns them, e.g.
-  `ace-task update <step-ref> --set worktree=.ace-wt/<task>/`.
+  `ace-task update <step-ref> --set assignment=<actual-id> --set role=<allocated-role> --set worktree=<actual-path>`.
+  Read back the fields; notes alone do not bind reports. `role=planner` denotes
+  only the allocation that prepares assignments, never bootstrap-worker or
+  confirmation of a running project. Resolve note folders from `ace-task show`;
+  never guess their title-derived paths.
 
 - Cross-task ordering goes through the integration step: a step of task B
   that requires A's merge depends on A's *integrate* subtask, not on A's
@@ -162,8 +167,9 @@ When a report arrives (ace-hitl event or message):
 1. Match its message ID plus task/assignment/step references to the current
    order. A report that fits no open allocation is kept for clarification,
    not counted as success.
-2. Record the outcome and the processed report ID in the managing task /
-   step (task-folder notes), then update statuses:
+2. Persist the exact accepted event ID and result on the owning step:
+   `ace-task update <step-ref> --set processed_report=<event-id> --set report_result=<result>`.
+   Add evidence notes in the folder returned by `ace-task show`, then update statuses:
    `ace-task update <step-ref> --set status=done` (or keep open / escalate).
 3. For success: end the current allocation, then continue with the next
    unblocked step per rule 3. For a repeated report: check the recorded
@@ -174,14 +180,23 @@ When a report arrives (ace-hitl event or message):
 
 `ace-overseer process-reports` executes rules 1-3 mechanically: it matches
 each incoming event (assignment recorded on a step, or the managing task's
-project_task with exactly one non-terminal step), records the outcome and
+project_task with exactly one explicitly allocated `role=planner` non-terminal
+step having no assignment). Task and any supplied role must agree; an event
+without an ID is refused. Unassigned readiness never closes worker, verifier,
+integration or confirm-start allocations. Before recording assigned success, the processor reads the actual coworker role
+allocation and ace-assign state: exact task/assignment/role, a completed nonempty
+plan, and every step done are required in dry-run and apply. Unavailable owner
+state refuses acceptance. It records the outcome and
 the processed report ID on the step through the ordinary ace-task update
 surface, and continues with the next unblocked step through the existing
 gates — `ace-overseer handoff` for the next role when the family records a
 worktree, otherwise the `work-on` dependency gate. A repeated delivery is
 answered from the recorded `processed_report` and re-runs nothing; an error
 report or question never advances a step; a report matching no open
-allocation stays for clarification. `--dry-run` interprets without effects.
+allocation stays for clarification. A `role=confirm-start` continuation remains
+a coordinator operation; no generic worker is dispatched and no managing task
+closes until first-turn and observation evidence is accepted. `--dry-run`
+interprets without effects.
 
 ### 6) Close
 

data/lib/ace/overseer/atoms/report_interpretation.rb

@@ -15,7 +15,7 @@ module Ace
       #   assignment that matches no step is :unmatched), or — only for
       #   reports without an assignment (planner readiness) — by the
       #   managing task's project_task plus exactly one non-terminal
-      #   step whose own assignment is blank (the preparation role). An
+      #   step explicitly allocated to role planner with no assignment. An
       #   event that fits no open allocation is :unmatched, kept
       #   for clarification, never success (an ambiguous cross-manager
       #   match is also :unmatched).
@@ -45,6 +45,8 @@ module Ace
         #      recorded_result:}
         #   {status: :unmatched, reason:}
         def self.evaluate(event:, managers:)
+          return {status: :unmatched, reason: "event has no report identity"} if event["id"].to_s.strip.empty?
+
           matched = match(event, managers)
           return {status: :unmatched, reason: unmatched_reason(event)} unless matched
 
@@ -142,16 +144,11 @@ module Ace
         # because a stale report for a different assignment must never
         # complete whichever step happens to remain.
         #
-        # Without an assignment (a planner readiness report carries task
-        # + result only) the report binds to the PREPARATION role alone:
-        # the managing task's project_task must match the reported task
-        # AND leave exactly one non-terminal step whose own assignment is
-        # blank (the preparation step). A sole remaining step that is
-        # bound to a role assignment belongs to that role, not to the
-        # report — absence of an assignment is never evidence that
-        # whichever role remains just finished. A match that is ambiguous
-        # across managers (or across steps) fits no open allocation and
-        # returns nil.
+        # Unassigned readiness can complete only an explicitly allocated
+        # planner step. A missing assignment says nothing about the role:
+        # confirm-start and bootstrap execution also have unassigned windows.
+        # Task identity and any supplied role must agree with the allocation.
+        # Ambiguous allocations never advance.
         #
         # @return [Hash{manager:, step:, terminal:}, nil]
         def self.match(event, managers)
@@ -161,8 +158,10 @@ module Ace
           assignment = event["assignment"].to_s
           if assignment != ""
             matches = managers.flat_map do |manager|
+              next [] unless task_agrees?(event, manager)
+
               steps_of(manager).filter_map do |step|
-                {manager: manager, step: step} if step.metadata["assignment"].to_s == assignment
+                {manager: manager, step: step} if step.metadata["assignment"].to_s == assignment && role_agrees?(event, step)
               end
             end
             # No step records this assignment: unmatched, never a
@@ -182,7 +181,9 @@ module Ace
             next unless manager.metadata["project_task"].to_s == task && task != ""
 
             active = steps_of(manager).reject { |step| terminal?(step) }
-            preparation = active.reject { |step| step.metadata["assignment"].to_s != "" }
+            preparation = active.select do |step|
+              step.metadata["assignment"].to_s.empty? && step.metadata["role"] == "planner" && role_agrees?(event, step)
+            end
             {manager: manager, step: preparation.first} if preparation.size == 1
           end
           return nil if matches.size > 1
@@ -201,7 +202,9 @@ module Ace
         def self.recorded_match(event, managers)
           matches = managers.flat_map do |manager|
             steps_of(manager).filter_map do |step|
-              {manager: manager, step: step} if step.metadata[PROCESSED_REPORT_KEY] == event["id"]
+              {manager: manager, step: step} if step.metadata[PROCESSED_REPORT_KEY] == event["id"] &&
+                task_agrees?(event, manager) && role_agrees?(event, step) &&
+                (event["assignment"].to_s.empty? || step.metadata["assignment"].to_s == event["assignment"].to_s)
             end
           end
           return nil if matches.size != 1
@@ -210,6 +213,17 @@ module Ace
            terminal: terminal?(matches.first[:step])}
         end
 
+        def self.task_agrees?(event, manager)
+          expected = manager.metadata["project_task"].to_s
+          actual = event["task"].to_s
+          expected.empty? || expected == actual
+        end
+
+        def self.role_agrees?(event, step)
+          role = event["role"].to_s
+          role.empty? || step.metadata["role"].to_s == role
+        end
+
         # @return [String] why the event fit no open allocation
         def self.unmatched_reason(event)
           refs = []

data/lib/ace/overseer/molecules/hitl_inbox.rb

@@ -34,6 +34,7 @@ module Ace
             "result" => event.result,
             "task" => event.metadata["task"],
             "assignment" => event.metadata["assignment"],
+            "role" => event.metadata["role"],
             "title" => event.title
           }
         end

data/lib/ace/overseer/molecules/project_bundle.rb

@@ -3,6 +3,9 @@
 require "json"
 require "ace/herdr/molecules/bounded_process"
 require "shellwords"
+require "tempfile"
+require "securerandom"
+require "fileutils"
 require "ace/support/cli/toolchain"
 
 module Ace
@@ -59,19 +62,53 @@ module Ace
         end
 
         def self.shell_setup(root, env: ENV)
+          values = environment(root, env: env).reject { |name, _| %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID].include?(name) }
           if Ace::Support::Cli::Toolchain.installed?
             # A server-created shell may contain selectors absent from this
             # caller. Clear the same known selectors before applying the
             # installed closure; never inherit server-side Bundler injection.
             names = BUNDLE_SELECTORS + BUNDLE_SELECTORS.map { |key| "BUNDLER_ORIG_#{key}" }
-            return "unset #{names.map { |name| Shellwords.escape(name) }.join(' ')}; " +
-              Ace::Support::Cli::Toolchain.shell_setup
+            values = names.to_h { |name| [name, nil] }.merge(values)
           end
 
-          values = environment(root, env: env).reject { |name, _| %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID].include?(name) }
           cleared, assigned = values.partition { |_, value| value.nil? }
-          "unset #{cleared.map { |name, _| Shellwords.escape(name) }.join(" ")}; export " +
-            assigned.map { |name, value| "#{name}=#{Shellwords.escape(value)}" }.join(" ")
+          # Guard every operation: e.g. a readonly inherited selector must
+          # refuse setup rather than print readiness after a failed unset.
+          commands = cleared.map { |name, _| "unset #{Shellwords.escape(name)}" } +
+            assigned.map { |name, value| "export #{name}=#{Shellwords.escape(value)}" }
+          commands.join(" &&\n")
+        end
+
+        # pane_run types through a terminal: Linux canonical input truncates
+        # a line after 4095 bytes. Keep the environment in a private shared
+        # project file, not /tmp (Herdr can use a different PrivateTmp).
+        # The caller must observe the marker before launching the harness.
+        def self.with_shell_setup(root, env: ENV)
+          directory = root
+          %w[.ace-local overseer runtime-start].each do |part|
+            directory = File.join(directory, part)
+            raise Ace::Overseer::Error, "runtime setup directory is a symlink: #{directory}" if File.symlink?(directory)
+
+            Dir.mkdir(directory, 0o700) unless File.exist?(directory)
+            raise Ace::Overseer::Error, "runtime setup path is not a directory: #{directory}" unless File.directory?(directory)
+          end
+          info = File.stat(directory)
+          unless info.uid == Process.uid && (info.mode & 0o077).zero?
+            raise Ace::Overseer::Error, "runtime setup directory must be private and owned by the current user: #{directory}"
+          end
+          marker = "ACE_OVERSEER_ENV_READY_#{SecureRandom.hex(16)}"
+          Tempfile.create(["environment-", ".sh"], directory) do |file|
+            setup = shell_setup(root, env: env).strip.sub(/;\z/, "")
+            file.write("#{setup} && printf '%s\\n' #{Shellwords.escape(marker)}\n")
+            file.flush
+            file.fsync
+            # The tab is created in root. An explicit ./ prevents dot from
+            # searching PATH; a relative path also keeps terminal input short.
+            relative = "./.ace-local/overseer/runtime-start/#{File.basename(file.path)}"
+            yield ". #{Shellwords.escape(relative)}", marker
+          end
+        rescue SystemCallError => e
+          raise Ace::Overseer::Error, "runtime setup file could not be prepared: #{e.message}"
         end
 
         def initialize(timeout_s: 240)
@@ -97,6 +134,13 @@ module Ace
           raise Ace::Overseer::Error, "project start output exceeded its limit" if result.oversized
           out, err, status = result.stdout, result.stderr, result.status
           report = JSON.parse(out)
+          # Startup can fail before it establishes project scope. Keep that
+          # concrete failure without admitting an unscoped report as ready.
+          if report.is_a?(Hash) && report["status"] == "blocked" &&
+              report.key?("scope") && report["scope"].nil? &&
+              report["message"].is_a?(String) && !report["message"].strip.empty?
+            raise Ace::Overseer::Error, report["message"]
+          end
           unless report.is_a?(Hash) && report["scope"] == "project" && report["status"].is_a?(String)
             raise Ace::Overseer::Error, "project start returned no project-scope report"
           end

data/lib/ace/overseer/molecules/report_completion_check.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ace
+  module Overseer
+    module Molecules
+      # Read existing coworker allocation and ace-assign completion truth before
+      # the queue accepts success. This check owns no persisted state.
+      class ReportCompletionCheck
+        def initialize(handoff_probe: nil, assignment_probe_factory: nil, worktree_finder: nil)
+          @worktree_finder = worktree_finder || Ace::Git::Worktree::Organisms::WorktreeManager.new
+          @handoff_probe = handoff_probe || HandoffProbe.new
+          @assignment_probe_factory = assignment_probe_factory || ->(root) {
+            Ace::Coworker::Molecules::AssignmentProbe.new(project_root: root)
+          }
+        end
+
+        def call(event:, manager:, step:)
+          return "matched task allocation no longer exists" unless manager && step
+          assignment = event["assignment"].to_s
+          if assignment.empty?
+            return nil if step.metadata["role"] == "planner" && step.metadata["assignment"].to_s.empty?
+            return "unassigned readiness is not execution completion"
+          end
+          task = manager.metadata["project_task"].to_s
+          role = step.metadata["role"].to_s
+          worktree = step.metadata["worktree"].to_s
+          worktree = manager.metadata["worktree"].to_s if worktree.empty?
+          return "success requires recorded project task, role and worktree" if [task, role, worktree].any?(&:empty?)
+          return "report task disagrees with the allocation" unless event["task"].to_s == task
+          return "confirm-start requires coordinator session evidence" if role == "confirm-start"
+          return "report assignment disagrees with the allocation" unless step.metadata["assignment"].to_s == assignment
+
+          found = @worktree_finder.switch(task)
+          return "task has no usable worktree: #{found[:error] || found[:message]}" unless found[:success]
+          root = found.fetch(:worktree_path)
+          legs = @handoff_probe.probe(root, task_id: task).fetch(:legs)
+          matching = legs.select { |leg| leg["assignment"] == assignment }
+          return "assignment has no unique allocation for this task" unless matching.size == 1
+          return "assignment role disagrees with the recorded allocation" unless matching.first["role"] == role
+          return "report role disagrees with the allocation" unless event["role"].to_s.empty? || event["role"] == role
+
+          snapshot = @assignment_probe_factory.call(root).snapshot(assignment)
+          return "assignment owner returned a different identity" unless snapshot.id == assignment
+          return "assignment is not complete: #{snapshot.incomplete_reasons.join('; ')}" unless snapshot.completion_verdict == :complete
+          nil
+        rescue Ace::Coworker::Error, Ace::Overseer::Error, SystemCallError, KeyError, Psych::Exception => e
+          "assignment completion could not be verified in #{worktree}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/report_processor.rb

@@ -16,7 +16,8 @@ module Ace
       class ReportProcessor
         OUTCOME_STATUSES = %i[success error needs_answer duplicate unmatched].freeze
 
-        def initialize(inbox: nil, task_manager: nil, handoff: nil, work_on: nil)
+        def initialize(inbox: nil, task_manager: nil, handoff: nil, work_on: nil, completion_check: nil)
+          @completion_check = completion_check || Molecules::ReportCompletionCheck.new
           @inbox = inbox || Molecules::HitlInbox.new
           @task_manager = task_manager || Ace::Task::Organisms::TaskManager.new
           @handoff = handoff || Organisms::HandoffOrchestrator.new(task_loader: @task_manager)
@@ -45,6 +46,12 @@ module Ace
         def process_event(event, dry_run:, progress:)
           verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: private_managers)
 
+          if verdict[:status] == :success || (verdict[:status] == :duplicate && verdict[:recorded_result] == "success")
+            refusal = @completion_check.call(event: event,
+              manager: @task_manager.show(verdict[:manager_ref]), step: @task_manager.show(verdict[:step_ref]))
+            verdict = {status: :unmatched, reason: refusal} if refusal
+          end
+
           case verdict[:status]
           when :unmatched
             progress.call("Event #{event['id']}: #{verdict[:reason]}")
@@ -135,6 +142,11 @@ module Ace
             return {action: "none", reason: reason}
           end
 
+          if next_step.metadata["role"] == "confirm-start"
+            return {action: "coordinator", step_ref: next_step.id.to_s,
+                    reason: "confirm project first turn and active eyes through the standard start operation; keep this step and manager open until proven"}
+          end
+
           begin
             if family_worktree(manager)
               result = @handoff.call(task_ref: manager.metadata["project_task"].to_s)
@@ -217,7 +229,7 @@ module Ace
           case continuation[:action]
           when "handoff"
             if continuation[:status] == "sequence_complete"
-              "sequence complete - the worktree has no next role; close the managing task per the queue workflow"
+              "sequence complete - the worktree has no next role; pending coordination steps still require acceptance before closing the managing task"
             elsif continuation[:start_command]
               "window ensured in #{continuation[:worktree_path]} for the next role " \
                 "(#{continuation.dig(:next, 'role')}); run there: #{continuation[:start_command]}"
@@ -231,6 +243,7 @@ module Ace
             else
               "next step #{continuation[:step_ref]} started via work-on"
             end
+          when "coordinator" then "coordinator action for #{continuation[:step_ref]}: #{continuation[:reason]}"
           when "blocked" then "continuation blocked: #{continuation[:reason]}"
           when "none" then continuation[:reason]
           end

data/lib/ace/overseer/organisms/start_orchestrator.rb

@@ -576,7 +576,10 @@ module Ace
               "herdr created tab '#{label}' but reported no root pane"
           end
 
-          @executor.pane_run(pane, Molecules::ProjectBundle.shell_setup(root, env: @env))
+          Molecules::ProjectBundle.with_shell_setup(root, env: @env) do |command, marker|
+            @executor.pane_run(pane, command)
+            @executor.pane_wait_output(pane, pattern: marker, timeout_ms: START_TIMEOUT_MS)
+          end
           args = ["--model", plan["profile"]["model"]]
           if plan["profile"]["thinking"]
             args += ["--thinking", plan["profile"]["thinking"]]
@@ -586,6 +589,8 @@ module Ace
           @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
             pane: pane, timeout_ms: START_TIMEOUT_MS, args: args)
           pane
+        rescue Ace::Herdr::WaitTimeoutError => e
+          raise Ace::Overseer::Error, "runtime setup was not confirmed; agent not started: #{e.message}"
         rescue Ace::Herdr::CommandError => e
           raise Ace::Overseer::Error, "herdr failed to start the overseer session: #{e.message}"
         end

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.28.0"
+    VERSION = "0.28.1"
   end
 end

data/lib/ace/overseer.rb

@@ -36,6 +36,7 @@ require_relative "overseer/molecules/assignment_launcher"
 require_relative "overseer/molecules/worktree_context_collector"
 require_relative "overseer/molecules/handoff_probe"
 require_relative "overseer/molecules/hitl_inbox"
+require_relative "overseer/molecules/report_completion_check"
 require_relative "overseer/molecules/local_sources"
 require_relative "overseer/molecules/remote_sources"
 require_relative "overseer/molecules/event_observation"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.28.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-31 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -353,6 +353,7 @@ files:
 - lib/ace/overseer/molecules/project_root_resolver.rb
 - lib/ace/overseer/molecules/prune_safety_checker.rb
 - lib/ace/overseer/molecules/remote_sources.rb
+- lib/ace/overseer/molecules/report_completion_check.rb
 - lib/ace/overseer/molecules/window_opener.rb
 - lib/ace/overseer/molecules/worktree_context_collector.rb
 - lib/ace/overseer/molecules/worktree_provisioner.rb