ace-assign 0.42.4 → 0.55.0

data/lib/ace/assign/cli/commands/step.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        # Print instructions for the focused active, next, or an explicit step.
+        class Step < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include AssignmentTarget
+
+          desc "Show instructions for the active, next, or explicit step"
+
+          argument :step, required: false, desc: "Exact step number to inspect"
+          option :assignment, desc: "Target specific assignment ID"
+          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 call(step: nil, **options)
+            target = resolve_assignment_target(options)
+            view = resolve_assignment_view(target)
+            inspected = resolve_step(view, step, target)
+
+            return if options[:quiet]
+
+            if inspected
+              puts inspected.instructions
+            else
+              puts no_work_message(view)
+            end
+          end
+
+          private
+
+          def resolve_step(view, explicit_step, target)
+            if explicit_step && !explicit_step.to_s.strip.empty?
+              step = view.state.find_by_number(explicit_step)
+              raise StepErrors::NotFound, "Step #{explicit_step} not found in queue" unless step
+
+              if target.scope && !target.scope.strip.empty? && !view.scoped_state.in_subtree?(target.scope, step.number)
+                raise StepErrors::NotFound, "Step #{explicit_step} is outside subtree #{target.scope}"
+              end
+
+              return step
+            end
+
+            view.focus_step
+          end
+
+          def no_work_message(view)
+            state_label = view.scoped_state.assignment_state.to_s
+            last_done = view.scoped_state.last_done ? "#{view.scoped_state.last_done.number} #{view.scoped_state.last_done.name}" : "none"
+            [
+              "Assignment: #{view.assignment.id} | Status: #{state_label} | Progress: #{view.scoped_state.done.size}/#{view.scoped_state.size} done",
+              "Last done: #{last_done} | No active or next workable step"
+            ].join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli.rb

@@ -31,6 +31,7 @@ require_relative "molecules/step_writer"
 require_relative "molecules/step_renumberer"
 require_relative "molecules/skill_assign_source_resolver"
 require_relative "molecules/fork_session_launcher"
+require_relative "molecules/tmux_control_surface_runner"
 require_relative "molecules/preset_inferrer"
 
 # Organisms
@@ -40,6 +41,7 @@ require_relative "organisms/assignment_executor"
 require_relative "cli/commands/create"
 require_relative "cli/commands/assignment_target"
 require_relative "cli/commands/status"
+require_relative "cli/commands/step"
 require_relative "cli/commands/start"
 require_relative "cli/commands/finish"
 require_relative "cli/commands/fail"
@@ -48,6 +50,7 @@ require_relative "cli/commands/retry_cmd"
 require_relative "cli/commands/list"
 require_relative "cli/commands/select"
 require_relative "cli/commands/fork_run"
+require_relative "cli/commands/fork_session"
 
 module Ace
   module Assign
@@ -61,6 +64,7 @@ module Ace
       REGISTERED_COMMANDS = [
         ["create", "Create assignment from preset or YAML"],
         ["status", "Show assignment status"],
+        ["step", "Show step instructions"],
         ["start", "Start next workable step"],
         ["finish", "Complete current step with report"],
         ["fail", "Mark step as failed"],
@@ -73,7 +77,8 @@ module Ace
 
       HELP_EXAMPLES = [
         "ace-assign create --preset review     # Start review assignment",
-        "ace-assign status                     # Current step progress",
+        "ace-assign status                     # Compact queue progress",
+        "ace-assign step                       # Current or next step instructions",
         "ace-assign start                      # Start next workable step",
         "ace-assign finish --message done.md    # Complete active step",
         "cat report.md | ace-assign finish     # Complete step via stdin",
@@ -115,6 +120,7 @@ module Ace
       # Register commands (wrapped to capture exit codes)
       register "create", wrap_command(Commands::Create)
       register "status", wrap_command(Commands::Status)
+      register "step", wrap_command(Commands::Step)
       register "start", wrap_command(Commands::Start)
       register "finish", wrap_command(Commands::Finish)
       register "fail", wrap_command(Commands::Fail)
@@ -123,6 +129,7 @@ module Ace
       register "list", wrap_command(Commands::List)
       register "select", wrap_command(Commands::Select)
       register "fork-run", wrap_command(Commands::ForkRun)
+      register "fork-session", wrap_command(Commands::ForkSession)
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/assign/models/assignment_info.rb

@@ -7,13 +7,13 @@ module Ace
       #
       # Pure data carrier with computed state (ATOM pattern).
       # Wraps an assignment with its queue state to provide
-      # computed state, progress, and current step information.
+      # computed state, progress, and active step information.
       #
       # @example
       #   info = AssignmentInfo.new(assignment: assignment, queue_state: state)
       #   info.state          # => :running
       #   info.progress       # => "2/5"
-      #   info.current_step  # => "020-implement"
+      #   info.step_focus    # => "implement"
       class AssignmentInfo
         attr_reader :assignment, :queue_state
 
@@ -39,13 +39,42 @@ module Ace
           "#{s[:done]}/#{s[:total]}"
         end
 
-        # Current step display string
+        # Active steps in queue order.
         #
-        # @return [String] Current step name or "-"
+        # @return [Array<Step>] Active steps
+        def active_steps
+          queue_state.active_steps
+        end
+
+        # Next pending workable step when nothing is active.
+        #
+        # @return [Step, nil] Next pending step or nil
+        def next_step
+          return nil unless active_steps.empty?
+
+          queue_state.next_workable
+        end
+
+        # Deterministic active step name kept for internal callers.
+        #
+        # @return [String] Focused active step name or "-"
         def current_step
           queue_state.current&.name || "-"
         end
 
+        # Human-friendly active/next summary for compact tables.
+        #
+        # @return [String] Active step names or next-step hint
+        def step_focus
+          if active_steps.any?
+            active_steps.map(&:name).join(", ")
+          elsif next_step
+            "next: #{next_step.name}"
+          else
+            "-"
+          end
+        end
+
         # Check if assignment is completed
         #
         # @return [Boolean]

data/lib/ace/assign/models/queue_state.rb

@@ -10,7 +10,7 @@ module Ace
       #
       # @example
       #   state = QueueState.new(steps: steps, assignment: assignment)
-      #   state.current  # => Step with status :in_progress
+      #   state.current  # => Deepest active step
       #   state.pending  # => Array of pending steps
       class QueueState
         attr_reader :steps, :assignment
@@ -23,16 +23,21 @@ module Ace
           @children_index = build_children_index(steps)
         end
 
-        # Get current in-progress step
-        # @return [Step, nil] Current step or nil
+        # Get the deterministic single-step active target.
+        #
+        # Returns the deepest active step in queue order. When several active
+        # branches exist globally, this is an internal convenience only; public
+        # status should use active_steps.
+        #
+        # @return [Step, nil] Deepest active step or nil
         def current
-          in_progress_steps.first
+          deepest_active
         end
 
-        # Get all in-progress steps
-        # @return [Array<Step>] In-progress steps
-        def in_progress_steps
-          steps.select { |s| s.status == :in_progress }
+        # Get all active steps in queue order.
+        # @return [Array<Step>] Active steps
+        def active_steps
+          steps.select { |s| s.status == :active }
         end
 
         # Get all pending steps
@@ -65,7 +70,7 @@ module Ace
           steps.empty?
         end
 
-        # Check if all steps are complete (no pending or in_progress)
+        # Check if all steps are complete (no pending or active)
         # @return [Boolean]
         def complete?
           steps.all?(&:complete?)
@@ -107,28 +112,28 @@ module Ace
         # - :empty     - No steps in queue
         # - :completed - All steps complete (done or failed)
         # - :failed    - Has failed step(s) but NOT all complete (stuck)
-        # - :running   - Has in_progress step with recent activity (< 1 hour)
-        # - :stalled   - Has in_progress step but stale (> 1 hour)
-        # - :paused    - Has pending but no in_progress (interrupted)
+        # - :running   - Has active step(s) with recent activity (< 1 hour)
+        # - :stalled   - Has active step(s) but all are stale (> 1 hour)
+        # - :paused    - Has pending but no active step (interrupted)
         #
         # @return [Symbol] Assignment state
         def assignment_state
           return :empty if empty?
           return :completed if complete?
           return :failed if failed.any?
-          return :running if current && recently_active?
-          return :stalled if current
+          return :running if active_steps.any? && recently_active?
+          return :stalled if active_steps.any?
 
           :paused
         end
 
-        # Check if the current in_progress step has recent activity
+        # Check if any active step has recent activity.
         # @param threshold [Integer] Seconds since started_at to consider active (default: 1 hour)
         # @return [Boolean]
         def recently_active?(threshold: 3600)
-          return false unless current&.started_at
-
-          (Time.now - current.started_at) < threshold
+          active_steps.any? do |step|
+            step.started_at && ((Time.now - step.started_at) < threshold)
+          end
         end
 
         # Summary for display
@@ -137,12 +142,19 @@ module Ace
           {
             total: size,
             done: done.size,
-            in_progress: in_progress_steps.size,
+            active: active_steps.size,
             pending: pending.size,
             failed: failed.size
           }
         end
 
+        # Get deepest active step in queue order.
+        #
+        # @return [Step, nil] Deepest active step
+        def deepest_active
+          deepest_active_from(active_steps)
+        end
+
         # Get all direct children of a step (O(1) via index)
         # @param parent_number [String] Parent step number
         # @return [Array<Step>] Direct child steps
@@ -193,21 +205,29 @@ module Ace
           subtree_steps(root_number).any? { |s| s.status == :failed }
         end
 
-        # Get the current in-progress step within a subtree.
+        # Get the deterministic active target within a subtree.
         #
         # @param root_number [String] Subtree root step number
-        # @return [Step, nil] In-progress step inside subtree, if any
+        # @return [Step, nil] Deepest active step inside subtree, if any
         def current_in_subtree(root_number)
-          in_progress_in_subtree(root_number).first
+          deepest_active_in_subtree(root_number)
         end
 
-        # Get all in-progress steps within a subtree.
+        # Get all active steps within a subtree.
         #
         # @param root_number [String] Subtree root step number
-        # @return [Array<Step>] In-progress steps inside subtree
-        def in_progress_in_subtree(root_number)
+        # @return [Array<Step>] Active steps inside subtree
+        def active_in_subtree(root_number)
           subtree_steps(root_number)
-            .select { |s| s.status == :in_progress }
+            .select { |s| s.status == :active }
+        end
+
+        # Get the deepest active step within a subtree.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Step, nil] Deepest active step in subtree
+        def deepest_active_in_subtree(root_number)
+          deepest_active_from(active_in_subtree(root_number))
         end
 
         # Get next workable step constrained to a subtree.
@@ -215,10 +235,7 @@ module Ace
         # @param root_number [String] Subtree root step number
         # @return [Step, nil] Next pending workable step inside subtree
         def next_workable_in_subtree(root_number)
-          subtree_steps(root_number)
-            .select { |s| s.status == :pending }
-            .reject { |s| has_incomplete_children?(s.number) }
-            .first
+          next_workable(scope_root: root_number)
         end
 
         # Build ancestor chain from closest parent to root.
@@ -260,19 +277,41 @@ module Ace
           children_of(parent_number).any? { |s| s.status != :done }
         end
 
-        # Get next workable step considering hierarchy.
+        # Get next workable pending step considering hierarchy and active fork ownership.
         # A step is workable if it's pending and has no incomplete children.
-        # Prefers children of current/recent work.
+        #
+        # Pending descendants under an active fork root are hidden unless the caller
+        # is explicitly scoped inside that root.
+        #
+        # @param scope_root [String, nil] Optional subtree scope
         # @return [Step, nil] Next step to work on
-        def next_workable
-          # First, find pending steps
-          pending_steps = pending
+        def next_workable(scope_root: nil)
+          candidate_steps = scope_root ? subtree_steps(scope_root) : steps
+          candidate_steps
+            .select { |s| s.status == :pending }
+            .reject { |s| has_incomplete_children?(s.number) && !runnable_delegation_parent?(s, scope_root: scope_root) }
+            .reject { |s| hidden_by_active_fork_root?(s.number, scope_root: scope_root) }
+            .first
+        end
 
-          # Filter to steps that don't have incomplete children
-          workable = pending_steps.reject { |s| has_incomplete_children?(s.number) }
+        # Get active fork roots in queue order.
+        #
+        # @return [Array<Step>] Active fork-scoped steps
+        def active_fork_roots
+          active_steps.select(&:fork?)
+        end
 
-          # Return first workable step (already sorted by number)
-          workable.first
+        # Check whether active steps inside a subtree fan out across more than one branch.
+        #
+        # @param root_number [String] Subtree root step number
+        # @param extra_active [Array<String>] Additional active step numbers to include
+        # @return [Boolean] True when active steps inside the subtree are not on a single path
+        def active_branch_conflict_in_subtree?(root_number, extra_active: [])
+          active_numbers = active_in_subtree(root_number).map(&:number) + Array(extra_active).map(&:to_s)
+          unique_active = active_numbers.uniq
+          unique_active.combination(2).any? do |left, right|
+            !(in_subtree?(left, right) || in_subtree?(right, left))
+          end
         end
 
         # Get all step numbers as an array
@@ -295,6 +334,12 @@ module Ace
 
         private
 
+        def runnable_delegation_parent?(step, scope_root:)
+          return false unless scope_root.nil? || scope_root.to_s.strip.empty?
+
+          step.batch_parent == true || step.fork?
+        end
+
         # Build index of children by parent number for O(1) lookups
         # @param steps [Array<Step>] All steps
         # @return [Hash<String, Array<Step>>] Parent number => children mapping
@@ -321,6 +366,23 @@ module Ace
             }
           end
         end
+
+        def deepest_active_from(active)
+          return nil if active.empty?
+
+          max_depth = active.map { |step| step.number.to_s.split(".").length }.max
+          active.find { |step| step.number.to_s.split(".").length == max_depth }
+        end
+
+        def hidden_by_active_fork_root?(step_number, scope_root:)
+          active_fork_roots.any? do |root|
+            next false if step_number == root.number
+            next false unless in_subtree?(root.number, step_number)
+            next false if scope_root && in_subtree?(root.number, scope_root)
+
+            true
+          end
+        end
       end
     end
   end

data/lib/ace/assign/models/step.rb

@@ -17,13 +17,13 @@ module Ace
       #   )
       class Step
         # Valid status values
-        STATUSES = %i[pending in_progress done failed].freeze
+        STATUSES = %i[pending active done failed].freeze
 
         # Valid context values for execution context
         VALID_CONTEXTS = %w[fork].freeze
 
         attr_reader :number, :name, :status, :instructions, :report, :error,
-          :started_at, :completed_at, :added_by, :parent, :file_path, :skill, :context,
+          :started_at, :completed_at, :added_by, :parent, :file_path, :source, :skill, :context,
           :workflow,
           :batch_parent, :parallel, :max_parallel, :fork_retry_limit, :fork_options,
           :fork_launch_pid, :fork_tracked_pids, :fork_pid_updated_at, :fork_pid_file,
@@ -31,7 +31,7 @@ module Ace
 
         # @param number [String] Step number (e.g., "010", "010.01")
         # @param name [String] Step name
-        # @param status [Symbol] Step status (:pending, :in_progress, :done, :failed)
+        # @param status [Symbol] Step status (:pending, :active, :done, :failed)
         # @param instructions [String] Step instructions (markdown)
         # @param report [String, nil] Completion report content
         # @param error [String, nil] Error message (if failed)
@@ -54,7 +54,7 @@ module Ace
         # @param stall_reason [String, nil] Last agent message captured when fork stalled
         def initialize(number:, name:, status:, instructions:, report: nil, error: nil,
           started_at: nil, completed_at: nil, added_by: nil, parent: nil,
-          file_path: nil, skill: nil, workflow: nil, context: nil,
+          file_path: nil, source: nil, skill: nil, workflow: nil, context: nil,
           batch_parent: nil, parallel: nil, max_parallel: nil, fork_retry_limit: nil,
           fork_options: nil,
           fork_launch_pid: nil, fork_tracked_pids: nil, fork_pid_updated_at: nil,
@@ -78,6 +78,7 @@ module Ace
           @added_by = added_by&.freeze
           @parent = parent&.freeze
           @file_path = file_path&.freeze
+          @source = source&.freeze
           @skill = skill&.freeze
           @workflow = workflow&.freeze
           @context = context&.freeze
@@ -102,7 +103,7 @@ module Ace
         # Check if step can be worked on
         # @return [Boolean]
         def workable?
-          status == :pending || status == :in_progress
+          status == :pending || status == :active
         end
 
         # Check if this is a retry of another step
@@ -127,6 +128,16 @@ module Ace
           provider.empty? ? nil : provider
         end
 
+        # Resolve per-step launch-mode override from fork options.
+        # @return [String, nil]
+        def fork_mode
+          return nil unless fork_options
+
+          mode = fork_options["mode"]
+          mode = mode.to_s.strip
+          mode.empty? ? nil : mode
+        end
+
         # Get the original step number if this is a retry
         # @return [String, nil] Original step number
         def retry_of
@@ -141,6 +152,7 @@ module Ace
           {
             "name" => name,
             "status" => status.to_s,
+            "source" => source,
             "skill" => skill,
             "workflow" => workflow,
             "context" => context,