ace-overseer 0.27.0 → 0.28.1

data/lib/ace/overseer/cli/commands/start.rb

@@ -16,19 +16,36 @@ module Ace
 
           desc "Start or reuse the project overseer session from .ace/overseer/config.yml"
 
+          option :reconcile, type: :boolean, default: false, desc: "Explicitly reconcile configured project overseers without restarting the lab coordinator"
+          option :scope, type: :string, desc: "Coordinator role (lab or project); omitted means lab bootstrap"
           option :dry_run, type: :boolean, default: false, desc: "Show the start plan without creating a session"
           option :format, default: "table", desc: "Output format (table, json)"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
 
-          def initialize(orchestrator: nil, config: nil)
+          def initialize(orchestrator: nil, config: nil, launcher: nil)
             super()
             @orchestrator = orchestrator
             @config = config
+            @launcher = launcher || ->(argv) { Kernel.exec(*argv) }
           end
 
-          def call(dry_run: false, format: "table", **options)
-            report = orchestrator.call(dry_run: dry_run)
+          def call(dry_run: false, format: "table", scope: nil, reconcile: false, **options)
+            unless scope.nil? || Atoms::StartContract::SCOPES.include?(scope)
+              raise Ace::Support::Cli::Error, "scope must be lab or project"
+            end
+            if reconcile && scope == "project"
+              raise Ace::Support::Cli::Error, "--reconcile requires lab scope"
+            end
+            operation = orchestrator(scope: scope)
+            report = if reconcile
+              operation.reconcile(dry_run: dry_run)
+            elsif scope
+              operation.call(dry_run: dry_run)
+            else
+              operation.bootstrap(dry_run: dry_run)
+            end
+            return @launcher.call(report.fetch("command")) if report["status"] == "foreground"
 
             if options[:quiet]
               # quiet still fails loudly on a blocked start
@@ -51,24 +68,24 @@ module Ace
 
           private
 
-          def orchestrator
-            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config)
+          def orchestrator(scope: nil)
+            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config, scope: scope)
           end
 
           def render_table(report)
-            puts "ace-overseer start: #{report['status']}"
-            puts "  scope:         #{report['scope'] || '-'}"
-            puts "  root:          #{report['root'] || '-'}"
-            puts "  label:         #{report['label'] || '-'}"
-            puts "  profile:       #{report['profile'] || '-'}"
+            puts "ace-overseer start: #{report["status"]}"
+            puts "  scope:         #{report["scope"] || "-"}"
+            puts "  root:          #{report["root"] || "-"}"
+            puts "  label:         #{report["label"] || "-"}"
+            puts "  profile:       #{report["profile"] || "-"}"
             if report["instructions"]
-              puts "  instructions:  #{report['instructions']['source']} -> #{report['instructions']['path']}"
+              puts "  instructions:  #{report["instructions"]["source"]} -> #{report["instructions"]["path"]}"
             end
-            puts "  workspace:     #{report['workspace'] || '-'}"
-            puts "  pane:          #{report['pane'] || '-'}"
-            puts "  agent:         #{report['agent']}"
-            puts "  replaced pane: #{report['replaced_pane'] || '-'}" if report["replaced_pane"]
-            puts "  #{report['message']}" if report["message"]
+            puts "  workspace:     #{report["workspace"] || "-"}"
+            puts "  pane:          #{report["pane"] || "-"}"
+            puts "  agent:         #{report["agent"]}"
+            puts "  replaced pane: #{report["replaced_pane"] || "-"}" if report["replaced_pane"]
+            puts "  #{report["message"]}" if report["message"]
           end
         end
       end

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

@@ -44,8 +44,9 @@ module Ace
             sources = local.fetch("sources").merge(remote.fetch("sources")).merge(
               "hitl" => {"status" => "degraded", "error" => "#{hitl_error.class}: #{hitl_error.message}"}
             )
+            ensure_budget!(events.length, limit)
             return {"schema" => "ace.hitl.observation/v1",
-                    "events" => events.sort_by { |row| row["key"] },
+                    "events" => wire_events(events).sort_by { |row| row["key"] },
                     "settled" => [], "sources" => sources}
           end
 
@@ -60,7 +61,8 @@ module Ace
             manager && ([manager] + Array(manager.subtasks)).all? { |task| Ace::Task::Atoms::TaskValidationRules.terminal_status?(task.status.to_s) }
           end
 
-          projection.merge("events" => (pending + local.fetch("events") + remote.fetch("events"))
+          ensure_budget!(pending.length + settled.length + local.fetch("events").length + remote.fetch("events").length, limit)
+          projection.merge("events" => (pending + wire_events(local.fetch("events") + remote.fetch("events")))
               .sort_by { |row| row["key"] },
             "settled" => settled,
             "sources" => local.fetch("sources").merge(remote.fetch("sources"))
@@ -69,6 +71,23 @@ module Ace
 
         private
 
+        def ensure_budget!(count, limit)
+          return if count <= limit
+
+          raise ArgumentError, "observation has #{count} rows, exceeding limit #{limit}; increase maxEvents/--limit or archive accepted history before arming eyes"
+        end
+
+        # Local owners expose readable keys, whereas eyes consumes the HITL
+        # wire envelope (hashed key, revision and a safe id). Normalize only
+        # local/remote rows; canonical HITL identities remain untouched.
+        def wire_events(rows)
+          rows.map do |row|
+            key = Digest::SHA256.hexdigest("overseer:#{row.fetch('key')}")
+            row.merge("source_key" => row.fetch("key"), "source_id" => row["id"],
+              "key" => key, "id" => key)
+          end
+        end
+
         # Configured remote observation (8xs.t.pu0.4): the project's own
         # observe.remote.pull_requests list — never a scan of accessible
         # accounts. No configuration means no remote rows and no remote

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/herdr/molecules/bounded_process"
+require "shellwords"
+require "tempfile"
+require "securerandom"
+require "fileutils"
+require "ace/support/cli/toolchain"
+
+module Ace
+  module Overseer
+    module Molecules
+      # A project's own Gemfile/lock and binstub select its ACE version.
+      # Never load child project gems into the lab coordinator's process.
+      class ProjectBundle
+        # A new Herdr shell inherits the server environment, which may differ
+        # from this CLI's environment. Clear known Bundler selectors even
+        # when the requesting process did not have them set.
+        BUNDLE_SELECTORS = %w[
+          BUNDLE_ALLOW_OFFLINE_INSTALL BUNDLE_APP_CONFIG BUNDLE_AUTO_INSTALL
+          BUNDLE_BIN BUNDLE_BIN_PATH BUNDLE_CACHE_ALL BUNDLE_CACHE_ALL_PLATFORMS
+          BUNDLE_CACHE_PATH BUNDLE_CLEAN BUNDLE_CONSOLE BUNDLE_DEPLOYMENT
+          BUNDLE_DISABLE_CHECKSUM_VALIDATION BUNDLE_DISABLE_EXEC_LOAD
+          BUNDLE_DISABLE_LOCAL_BRANCH_CHECK BUNDLE_DISABLE_LOCAL_REVISION_CHECK
+          BUNDLE_DISABLE_SHARED_GEMS BUNDLE_DISABLE_VERSION_CHECK
+          BUNDLE_FORCE_RUBY_PLATFORM BUNDLE_FORGET_CLI_OPTIONS BUNDLE_FROZEN
+          BUNDLE_GEMFILE BUNDLE_GEM__BUNDLE BUNDLE_GEM__CHANGELOG BUNDLE_GEM__CI
+          BUNDLE_GEM__COC BUNDLE_GEM__GITHUB_USERNAME BUNDLE_GEM__LINTER
+          BUNDLE_GEM__MIT BUNDLE_GEM__RUBOCOP BUNDLE_GEM__TEST
+          BUNDLE_GIT__ALLOW_INSECURE BUNDLE_GLOBAL_GEM_CACHE BUNDLE_IGNORE_CONFIG
+          BUNDLE_IGNORE_MESSAGES BUNDLE_INIT_GEMS_RB BUNDLE_INLINE BUNDLE_JOBS
+          BUNDLE_LOCKFILE_CHECKSUMS BUNDLE_NO_INSTALL BUNDLE_NO_PRUNE BUNDLE_ONLY
+          BUNDLE_PATH BUNDLE_PATH__SYSTEM BUNDLE_PLUGINS BUNDLE_PREFER_PATCH
+          BUNDLE_REDIRECT BUNDLE_RETRY BUNDLE_SHEBANG BUNDLE_SILENCE_DEPRECATIONS
+          BUNDLE_SILENCE_ROOT_WARNING BUNDLE_SIMULATE_VERSION BUNDLE_SSL_CA_CERT
+          BUNDLE_SSL_CLIENT_CERT BUNDLE_SSL_VERIFY_MODE BUNDLE_SYSTEM_BINDIR
+          BUNDLE_TIMEOUT BUNDLE_TRUST___POLICY BUNDLE_UPDATE_REQUIRES_ALL_FLAG
+          BUNDLE_USER_HOME BUNDLE_USER_CONFIG BUNDLE_USER_CACHE BUNDLE_USER_PLUGIN
+          BUNDLE_VERBOSE BUNDLE_VERSION BUNDLE_WITH BUNDLE_WITHOUT
+          BUNDLER_SETUP BUNDLER_VERSION
+        ].freeze
+        RUBY_SELECTORS = %w[RUBYOPT RUBYLIB GEM_HOME GEM_PATH ACE_TOOLCHAIN].freeze
+
+        def self.environment(root, env: ENV)
+          if Ace::Support::Cli::Toolchain.installed?
+            # Reuse the installed closure; the project checkout is domain data.
+            # Do not let a project binstub or Gemfile select source dependencies.
+            return Ace::Support::Cli::Toolchain.child_environment.merge(
+              "HERDR_PANE" => nil, "HERDR_TAB" => nil,
+              "HERDR_PANE_ID" => nil, "HERDR_TAB_ID" => nil
+            )
+          end
+          known = BUNDLE_SELECTORS + RUBY_SELECTORS
+          names = env.keys.grep(/\ABUNDLER?_/) + known +
+            (known + %w[PATH]).map { |key| "BUNDLER_ORIG_#{key}" } +
+            %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID]
+          names.to_h { |name| [name, nil] }.merge(
+            "BUNDLE_GEMFILE" => File.file?(File.join(root, "Gemfile")) ? File.join(root, "Gemfile") : nil,
+            "PATH" => [File.join(root, "bin"), env.fetch("PATH", "/usr/bin:/bin")].join(File::PATH_SEPARATOR)
+          )
+        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}" }
+            values = names.to_h { |name| [name, nil] }.merge(values)
+          end
+
+          cleared, assigned = values.partition { |_, value| value.nil? }
+          # 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)
+          @timeout_s = timeout_s
+        end
+
+        def call(root:, workspace:, env: ENV)
+          installed = Ace::Support::Cli::Toolchain.installed?
+          unless installed
+            %w[Gemfile Gemfile.lock].each do |name|
+              unless File.file?(File.join(root, name))
+                raise Ace::Overseer::Error, "project bundle missing #{name}; prepare this project's own bundle first"
+              end
+            end
+          end
+          binary = installed ? Ace::Support::Cli::Toolchain.executable("ace-overseer") : File.join(root, "bin", "ace-overseer")
+          command = File.executable?(binary) ? [binary] : ["bundle", "exec", "ace-overseer"]
+          command += ["start", "--scope", "project", "--format", "json"]
+          child_env = self.class.environment(root, env: env).merge("HERDR_WORKSPACE_ID" => workspace)
+          result = Ace::Herdr::Molecules::BoundedProcess.call(command,
+            environment: ENV.to_h.merge(child_env).compact, chdir: root,
+            timeout_s: @timeout_s, output_limit: 1_048_576)
+          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
+          if !status.success? && %w[started reused ready].include?(report["status"])
+            raise Ace::Overseer::Error, "project start exited #{status.exitstatus} despite a ready report"
+          end
+          report
+        rescue Timeout::Error
+          raise Ace::Overseer::Error, "project start timed out after #{@timeout_s}s; inspect the existing session before retrying"
+        rescue Ace::Herdr::Molecules::BoundedProcess::PostLaunchError => e
+          raise Ace::Overseer::Error, "project start outcome is uncertain: #{e.message}"
+        rescue JSON::ParserError
+          raise Ace::Overseer::Error, "project bundle start returned invalid JSON#{": " + err.strip[0, 300] unless err.to_s.empty?}"
+        rescue SystemCallError => e
+          raise Ace::Overseer::Error, "project bundle could not start: #{e.message}"
+        end
+      end
+    end
+  end
+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