ace-assign 0.53.4 → 0.55.0

data/lib/ace/assign/molecules/tmux_control_surface_runner.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "ace/tmux"
+require "fileutils"
+require "shellwords"
+require "yaml"
+
+module Ace
+  module Assign
+    module Molecules
+      # Shared ace-tmux backed runtime helper for tmux fork launches.
+      class TmuxControlSurfaceRunner
+        def initialize(executor: Ace::Tmux::Molecules::TmuxExecutor.new, resolver: nil, control_surface: nil, tmux: "tmux", env: ENV)
+          @executor = executor
+          @tmux = tmux
+          @env = env
+          @resolver = resolver || Ace::Tmux::Molecules::RuntimeTargetResolver.new(executor: executor, tmux: tmux, env: env)
+          @control_surface = control_surface || Ace::Tmux::Organisms::ControlSurface.new(
+            executor: executor,
+            resolver: @resolver,
+            tmux: tmux
+          )
+        end
+
+        def tmux_context?
+          !current_session.to_s.strip.empty?
+        end
+
+        def current_session
+          resolver.resolve_session.session
+        rescue Ace::Tmux::TargetResolutionError
+          nil
+        end
+
+        def current_window
+          explicit = env["ACE_ASSIGN_FORK_WINDOW"].to_s.strip
+          return explicit unless explicit.empty?
+
+          resolver.resolve_window(session: current_session).window
+        rescue Ace::Tmux::TargetResolutionError
+          nil
+        end
+
+        def current_pane
+          explicit = env["ACE_ASSIGN_CALLBACK_PANE"].to_s.strip
+          return explicit unless explicit.empty?
+
+          resolver.resolve_pane(session: current_session, window: current_window).pane_target
+        rescue Ace::Tmux::TargetResolutionError
+          nil
+        end
+
+        def fork_window_name(base_window)
+          base = base_window.to_s.strip.sub(/-fs\z/, "")
+          sanitized = Ace::Tmux::Atoms::WindowNameSanitizer.call(base, fallback: "fork")
+
+          "#{sanitized}-fs"
+        end
+
+        def ensure_window(session:, name:, root:)
+          if (window_id = find_window_id(session: session, name: name))
+            return {created: false, target: window_id, window_id: window_id, name: name}
+          end
+
+          result = executor.capture(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.new_window(
+              session,
+              name: name,
+              root: root,
+              print_format: '#{window_id}',
+              tmux: tmux
+            )
+          )
+          raise Error, "Failed to create tmux fork window #{name}: #{result.stderr}" unless result.success?
+
+          window_id = result.stdout.to_s.strip
+          raise Error, "Failed to create tmux fork window #{name}: empty window id" if window_id.empty?
+
+          {created: true, target: window_id, window_id: window_id, name: name}
+        end
+
+        def prepare_pane(session:, window:, root:, keep_existing:, window_target: nil)
+          target = window_target || "#{session}:#{window}"
+          pane = if keep_existing
+            first_pane(target)
+          else
+            create_pane(target, root)
+          end
+
+          set_pane_remain_on_exit(pane)
+          select_layout(target)
+          pane
+        end
+
+        def select_window(session:, window:, window_target: nil)
+          target = window_target || "#{session}:#{window}"
+          run!(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.select_window(target, tmux: tmux),
+            "select tmux fork window #{window}"
+          )
+        end
+
+        def run_invocation_in_pane(pane_target:, command:, env: nil, working_dir: nil, visible_handoff: nil)
+          shell_command = build_pane_shell_command(
+            command: command,
+            env: env,
+            working_dir: working_dir,
+            visible_handoff: visible_handoff
+          )
+          control_surface.send_command(pane: pane_target, command: shell_command)
+        rescue Ace::Tmux::Error => e
+          raise Error, "Failed to send tmux fork command: #{e.message}"
+        end
+
+        def run_script_in_pane(pane_target:, script_path:)
+          control_surface.send_command(pane: pane_target, command: "bash #{File.expand_path(script_path).shellescape}")
+        rescue Ace::Tmux::Error => e
+          raise Error, "Failed to send tmux fork command: #{e.message}"
+        end
+
+        def capture_recent_output(pane_target:, lines: 40)
+          control_surface.capture_recent_output(pane: pane_target, lines: lines)
+        rescue Ace::Tmux::Error => e
+          raise Error, "Failed to capture pane #{pane_target}: #{e.message}"
+        end
+
+        def merge_tmux_metadata(session_meta_file:, session:, window:, pane:, window_id: nil, callback_pane: nil)
+          data = if File.exist?(session_meta_file)
+            YAML.safe_load_file(session_meta_file) || {}
+          else
+            {}
+          end
+          data["launch_mode"] = "tmux"
+          data["tmux_session"] = session
+          data["tmux_window"] = window
+          data["tmux_window_id"] = window_id if window_id
+          data["tmux_pane_id"] = pane
+          data["callback_pane"] = callback_pane if callback_pane && !callback_pane.empty?
+          File.write(session_meta_file, data.to_yaml)
+        end
+
+        private
+
+        attr_reader :control_surface, :env, :executor, :resolver, :tmux
+
+        def find_window_id(session:, name:)
+          result = executor.capture(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.list_windows(
+              session,
+              format: '#{window_id}' + "\t" + '#{window_name}',
+              tmux: tmux
+            )
+          )
+          return nil unless result.success?
+
+          result.stdout.split("\n").map(&:strip).reject(&:empty?).each do |line|
+            window_id, window_name = line.split("\t", 2)
+            return window_id if window_name == name && !window_id.to_s.empty?
+          end
+
+          nil
+        end
+
+        def first_pane(target)
+          result = executor.capture(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.list_panes(target, format: '#{pane_id}', tmux: tmux)
+          )
+          raise Error, "Failed to inspect panes for #{target}: #{result.stderr}" unless result.success?
+
+          pane = result.stdout.split("\n").map(&:strip).reject(&:empty?).first
+          raise Error, "No panes found for #{target}" if pane.to_s.empty?
+
+          pane
+        end
+
+        def create_pane(target, root)
+          result = executor.capture(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.split_window(
+              target,
+              root: root,
+              print_format: '#{pane_id}',
+              tmux: tmux
+            )
+          )
+          raise Error, "Failed to create tmux fork pane in #{target}: #{result.stderr}" unless result.success?
+
+          pane = result.stdout.to_s.strip
+          raise Error, "Failed to create tmux fork pane in #{target}: empty pane id" if pane.empty?
+
+          pane
+        end
+
+        def set_pane_remain_on_exit(pane_target)
+          run!(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.set_pane_option(pane_target, "remain-on-exit", "on", tmux: tmux),
+            "enable remain-on-exit"
+          )
+        end
+
+        def select_layout(target)
+          run!(
+            Ace::Tmux::Atoms::TmuxCommandBuilder.select_layout(target, "tiled", tmux: tmux),
+            "apply tiled layout"
+          )
+        end
+
+        def run!(cmd, action)
+          return if executor.run(cmd)
+
+          raise Error, "Failed to #{action}"
+        end
+
+        def build_pane_shell_command(command:, env:, working_dir:, visible_handoff:)
+          steps = []
+          resolved_working_dir = working_dir.to_s.strip
+          steps << "cd #{Shellwords.escape(File.expand_path(resolved_working_dir))}" unless resolved_working_dir.empty?
+
+          handoff = visible_handoff.to_s
+          steps << "printf '%s\\n' #{Shellwords.escape(handoff)}" unless handoff.empty?
+
+          steps << "exec #{build_exec_command(command: command, env: env)}"
+          steps.join(" && ")
+        end
+
+        def build_exec_command(command:, env:)
+          cmd = Array(command).map { |part| Shellwords.escape(part.to_s) }.join(" ")
+          env_hash = env.respond_to?(:to_h) ? env.to_h : {}
+          unset_parts = []
+          assign_parts = []
+
+          env_hash.each do |key, value|
+            next if key.to_s.strip.empty?
+
+            if value.nil?
+              unset_parts << "-u #{Shellwords.escape(key.to_s)}"
+            else
+              assign_parts << "#{key}=#{Shellwords.escape(value.to_s)}"
+            end
+          end
+          env_parts = unset_parts + assign_parts
+
+          return cmd if env_parts.empty?
+
+          "env #{env_parts.join(' ')} #{cmd}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/organisms/assignment_executor.rb

@@ -98,12 +98,6 @@ module Ace
             )
           end
 
-          # Mark first workable step as in_progress.
-          # This skips batch parent containers that have incomplete children.
-          initial_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          first_workable = initial_state.next_workable
-          step_writer.mark_in_progress(first_workable.file_path) if first_workable
-
           # Archive source config into task's steps directory and update assignment metadata
           archived_path = archive_source_config(config_path, assignment.id)
           assignment = Models::Assignment.new(
@@ -145,7 +139,6 @@ module Ace
         # Start a pending step.
         #
         # Rules:
-        # - Fails if any step is already in progress (strict mode)
         # - Starts an explicit pending target when provided
         # - Otherwise starts the next workable pending step
         #
@@ -157,7 +150,6 @@ module Ace
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          raise StepErrors::InvalidState, "Cannot start: step #{state.current.number} is already in progress. Finish or fail it first." if state.current
 
           fork_root = fork_root&.strip
           target_step = if step_number && !step_number.to_s.strip.empty?
@@ -176,7 +168,8 @@ module Ace
             raise StepErrors::InvalidState, "No pending workable step found."
           end
 
-          step_writer.mark_in_progress(target_step.file_path)
+          validate_start_activation!(state, target_step, fork_root: fork_root)
+          step_writer.mark_active(target_step.file_path)
           assignment_manager.update(assignment)
 
           new_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
@@ -188,10 +181,10 @@ module Ace
           }
         end
 
-        # Finish an in-progress step and advance queue state.
+        # Finish an active step and update queue state.
         #
         # @param report_content [String] Completion report content
-        # @param step_number [String, nil] Optional in-progress step number to finish
+        # @param step_number [String, nil] Optional active step number to finish
         # @param fork_root [String, nil] Optional subtree root to constrain advancement
         # @return [Hash] Result with completed step and updated state
         def finish_step(report_content:, step_number: nil, fork_root: nil)
@@ -200,7 +193,7 @@ module Ace
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
           current = find_target_step_for_finish(state, step_number, fork_root)
-          raise Error, "No step currently in progress. Try 'ace-assign start' or 'ace-assign retry'." unless current
+          raise Error, "No step currently active. Try 'ace-assign start' or 'ace-assign retry'." unless current
 
           # Enforce hierarchy: cannot mark parent as done with incomplete children
           if state.has_incomplete_children?(current.number)
@@ -221,18 +214,6 @@ module Ace
           # Re-scan to get fresh state after auto-completions
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
 
-          fork_root = fork_root&.strip
-          # Find next step to work on using hierarchical rules.
-          # When fork_root is provided, keep advancement inside that subtree.
-          next_step = if fork_root && !fork_root.empty? && state.find_by_number(fork_root)
-            find_next_step_in_subtree(state, current.number, fork_root)
-          else
-            find_next_step(state, current.number)
-          end
-          if next_step
-            step_writer.mark_in_progress(next_step.file_path)
-          end
-
           assignment_manager.update(assignment)
 
           new_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
@@ -244,13 +225,7 @@ module Ace
           }
         end
 
-        # Complete current step with report and advance
-        #
-        # Legacy bridge: preserves single-call semantics for fork-run callers.
-        # Previously, advance() auto-started the next step as a side effect.
-        # The new start/finish split makes this explicit, but advance() retains
-        # the auto-start behavior for subtree entry so fork-run workflows
-        # (which call advance() with fork_root) continue to work unchanged.
+        # Complete current step with report content from a file.
         #
         # @param report_path [String] Path to report file
         # @param fork_root [String, nil] Optional subtree root to constrain advancement
@@ -258,26 +233,6 @@ module Ace
         def advance(report_path, fork_root: nil)
           raise ConfigErrors::NotFound, "Report file not found: #{report_path}" unless File.exist?(report_path)
 
-          # Auto-start the next workable subtree step when fork_root is given but
-          # no step in the subtree is yet in_progress (subtree entry case).
-          fork_root_str = fork_root&.strip
-          if fork_root_str && !fork_root_str.empty?
-            assignment = assignment_manager.find_active
-            if assignment
-              state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-              active_in_subtree = state.in_progress_in_subtree(fork_root_str)
-              if active_in_subtree.size > 1
-                active_refs = active_in_subtree.map { |step| "#{step.number}(#{step.name})" }.join(", ")
-                raise StepErrors::InvalidState, "Cannot advance subtree #{fork_root_str}: multiple steps are in progress (#{active_refs})."
-              end
-
-              if active_in_subtree.empty?
-                next_workable = state.next_workable_in_subtree(fork_root_str)
-                step_writer.mark_in_progress(next_workable.file_path) if next_workable
-              end
-            end
-          end
-
           finish_step(report_content: File.read(report_path), fork_root: fork_root)
         end
 
@@ -285,13 +240,13 @@ module Ace
         #
         # @param message [String] Error message
         # @return [Hash] Result with updated state
-        def fail(message)
+        def fail(message, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          current = state.current
-          raise Error, "No step currently in progress. Try 'ace-assign add' to add a new step or 'ace-assign retry' to retry a failed step." unless current
+          current = find_target_step_for_fail(state, fork_root)
+          raise Error, "No step currently active. Try 'ace-assign add' to add a new step or 'ace-assign retry' to retry a failed step." unless current
 
           # Mark step as failed
           step_writer.mark_failed(current.file_path, error_message: message)
@@ -315,7 +270,7 @@ module Ace
         # @param after [String, nil] Insert after this step number (optional)
         # @param as_child [Boolean] Insert as child of 'after' step (default: false, sibling)
         # @return [Hash] Result with new step
-        def add(name, instructions, after: nil, as_child: false, added_by: nil, extra: {})
+        def add(name, instructions, after: nil, as_child: false, added_by: nil, extra: {}, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
@@ -323,6 +278,7 @@ module Ace
           raise Error, "Step name cannot be empty." if step_name.empty?
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          after, as_child = normalize_scoped_insertion_anchor(state, after: after, as_child: as_child, fork_root: fork_root)
           existing_numbers = queue_scanner.step_numbers(assignment.steps_dir)
 
           # Validate --after step exists
@@ -344,9 +300,6 @@ module Ace
             queue_scanner.step_numbers(assignment.steps_dir)
           end
 
-          # Determine initial status upfront to avoid redundant I/O
-          initial_status = state.current ? :pending : :in_progress
-
           # Build added_by metadata for audit trail
           added_by ||= if after && as_child
             "child_of:#{after}"
@@ -364,7 +317,7 @@ module Ace
             number: new_number,
             name: step_name,
             instructions: instructions,
-            status: initial_status,
+            status: :pending,
             added_by: added_by,
             parent: as_child ? after : nil,
             extra: extra_frontmatter
@@ -396,7 +349,7 @@ module Ace
         # @note Structural validation is performed for the full batch before any writes.
         #   Runtime I/O failures can still interrupt insertion after partial writes.
         # @return [Hash] Result with added steps and final state
-        def add_batch(steps:, after: nil, as_child: false, source_file: nil)
+        def add_batch(steps:, after: nil, as_child: false, source_file: nil, fork_root: nil)
           unless steps.is_a?(Array) && steps.any?
             source_label = source_file.to_s.strip.empty? ? "batch input" : source_file
             raise Error, "No steps defined in #{source_label}"
@@ -408,6 +361,12 @@ module Ace
 
           prevalidate_batch_trees!(steps)
 
+          assignment = assignment_manager.find_active
+          raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
+
+          state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          after, as_child = normalize_scoped_insertion_anchor(state, after: after, as_child: as_child, fork_root: fork_root)
+
           added_steps = []
           renumbered = []
           sibling_cursor = after
@@ -425,7 +384,6 @@ module Ace
             sibling_cursor = inserted[:root_number] unless as_child
           end
 
-          assignment = assignment_manager.find_active
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
           {
             assignment: assignment,
@@ -439,7 +397,7 @@ module Ace
         #
         # @param step_ref [String] Step number or reference to retry
         # @return [Hash] Result with new retry step
-        def retry_step(step_ref)
+        def retry_step(step_ref, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
@@ -448,16 +406,18 @@ module Ace
           # Find the step to retry
           original = state.find_by_number(step_ref.to_s)
           raise StepErrors::NotFound, "Step #{step_ref} not found in queue" unless original
+          validate_retry_scope!(state, original, fork_root)
 
           # Get existing numbers
           existing_numbers = queue_scanner.step_numbers(assignment.steps_dir)
 
           # Insert after all current steps (at end of queue before pending)
           # Find last done or failed step
-          base_number = if state.current
-            state.current.number
-          elsif state.last_done
-            state.last_done.number
+          scoped_state = scoped_retry_state(state, assignment: assignment, fork_root: fork_root)
+          base_number = if scoped_state.current
+            scoped_state.current.number
+          elsif scoped_state.last_done
+            scoped_state.last_done.number
           else
             original.number
           end
@@ -681,9 +641,11 @@ module Ace
           if parent_context == "fork"
             lines.concat(
               [
-                "Delegate this subtree into forked context:",
+                "Unscoped driver action: delegate this subtree into forked context:",
                 "- ace-assign fork-run --assignment <assignment-id>@{{parent_number}}",
-                "Inside the forked agent, continue execution within this subtree scope only."
+                "Scoped forked agent action: do not call fork-run again for {{parent_number}}.",
+                "If this scoped root is active and no child step is active yet: ace-assign start --assignment <assignment-id>@{{parent_number}}",
+                "After a child step becomes active, continue execution within this subtree scope only."
               ]
             )
           else
@@ -1394,13 +1356,11 @@ module Ace
         end
 
         def rebalance_after_child_injection(assignment:, state:, parent_number:)
-          current = state.current
-          return unless current && current.number == parent_number
+          parent = state.find_by_number(parent_number)
+          return unless parent&.status == :active
+          return if parent.fork?
 
-          step_writer.mark_pending(current.file_path)
-          rebalanced_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          next_step = rebalanced_state.next_workable_in_subtree(parent_number)
-          step_writer.mark_in_progress(next_step.file_path) if next_step
+          step_writer.mark_pending(parent.file_path)
         end
 
         # Normalize instructions to a string.
@@ -1714,6 +1674,28 @@ module Ace
           DEFAULT_DYNAMIC_STEP_INSTRUCTIONS
         end
 
+        def targeted_batch_parent_startable?(target, fork_root:)
+          return false unless fork_root.nil? || fork_root.empty?
+
+          target.batch_parent == true
+        end
+
+        def find_target_step_for_fail(state, fork_root)
+          fork_root = fork_root&.strip
+          current = state.current
+          return current if fork_root.nil? || fork_root.empty?
+
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
+          if state.active_branch_conflict_in_subtree?(fork_root)
+            active_refs = state.active_in_subtree(fork_root).map { |step| "#{step.number}(#{step.name})" }.join(", ")
+            raise StepErrors::InvalidState, "Cannot fail in subtree #{fork_root}: multiple active branches exist (#{active_refs})."
+          end
+
+          return current if current && state.in_subtree?(fork_root, current.number)
+
+          state.current_in_subtree(fork_root)
+        end
+
         def find_target_step_for_start(state, step_number, fork_root)
           target = state.find_by_number(step_number)
           raise StepErrors::NotFound, "Step #{step_number} not found in queue" unless target
@@ -1723,13 +1705,40 @@ module Ace
             raise StepErrors::InvalidState, "Step #{target.number} is outside scoped subtree #{fork_root}." unless state.in_subtree?(fork_root, target.number)
           end
           raise StepErrors::InvalidState, "Cannot start step #{target.number}: status is #{target.status}, expected pending." unless target.status == :pending
-          if state.has_incomplete_children?(target.number)
+          if state.has_incomplete_children?(target.number) && !targeted_batch_parent_startable?(target, fork_root: fork_root)
             raise StepErrors::InvalidState, "Cannot start step #{target.number}: has incomplete children."
           end
 
           target
         end
 
+        def validate_start_activation!(state, target, fork_root:)
+          root_ref = fork_root if fork_root && !fork_root.empty?
+          active_fork_root = if root_ref
+            state.find_by_number(root_ref)
+          else
+            state.nearest_fork_ancestor(target.number)
+          end
+
+          if active_fork_root &&
+              target.number != active_fork_root.number &&
+              active_fork_root.status != :active
+            raise StepErrors::InvalidState,
+              "Cannot start step #{target.number}: fork root #{active_fork_root.number} is not active."
+          end
+
+          return unless active_fork_root
+
+          if state.active_branch_conflict_in_subtree?(active_fork_root.number, extra_active: [target.number])
+            active_refs = (
+              state.active_in_subtree(active_fork_root.number).map { |step| "#{step.number}(#{step.name})" } +
+              ["#{target.number}(#{target.name})"]
+            ).uniq.join(", ")
+            raise StepErrors::InvalidState,
+              "Cannot start step #{target.number}: subtree #{active_fork_root.number} already has multiple active branches (#{active_refs})."
+          end
+        end
+
         def find_target_step_for_finish(state, step_number, fork_root)
           fork_root = fork_root&.strip
           if step_number && !step_number.to_s.strip.empty?
@@ -1738,7 +1747,7 @@ module Ace
             if fork_root && !fork_root.empty? && !state.in_subtree?(fork_root, target.number)
               raise StepErrors::InvalidState, "Step #{target.number} is outside scoped subtree #{fork_root}."
             end
-            raise StepErrors::InvalidState, "Cannot finish step #{target.number}: status is #{target.status}, expected in_progress." unless target.status == :in_progress
+            raise StepErrors::InvalidState, "Cannot finish step #{target.number}: status is #{target.status}, expected active." unless target.status == :active
 
             return target
           end
@@ -1746,10 +1755,9 @@ module Ace
           current = state.current
           if fork_root && !fork_root.empty?
             raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
-            active_in_subtree = state.in_progress_in_subtree(fork_root)
-            if active_in_subtree.size > 1
-              active_refs = active_in_subtree.map { |step| "#{step.number}(#{step.name})" }.join(", ")
-              raise StepErrors::InvalidState, "Cannot finish in subtree #{fork_root}: multiple steps are in progress (#{active_refs})."
+            if state.active_branch_conflict_in_subtree?(fork_root)
+              active_refs = state.active_in_subtree(fork_root).map { |step| "#{step.number}(#{step.name})" }.join(", ")
+              raise StepErrors::InvalidState, "Cannot finish in subtree #{fork_root}: multiple active branches exist (#{active_refs})."
             end
             if current.nil? || !state.in_subtree?(fork_root, current.number)
               current = state.current_in_subtree(fork_root)
@@ -1760,6 +1768,48 @@ module Ace
           current
         end
 
+        def scoped_retry_state(state, assignment:, fork_root:)
+          fork_root = fork_root&.strip
+          return state if fork_root.nil? || fork_root.empty?
+
+          scoped_steps = state.subtree_steps(fork_root)
+          Models::QueueState.new(steps: scoped_steps, assignment: assignment)
+        end
+
+        def validate_retry_scope!(state, original, fork_root)
+          fork_root = fork_root&.strip
+          return if fork_root.nil? || fork_root.empty?
+
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
+          return if state.in_subtree?(fork_root, original.number)
+
+          raise StepErrors::InvalidState, "Step #{original.number} is outside scoped subtree #{fork_root}."
+        end
+
+        def normalize_scoped_insertion_anchor(state, after:, as_child:, fork_root:)
+          fork_root = fork_root&.strip
+          return [after, as_child] if fork_root.nil? || fork_root.empty?
+
+          root = state.find_by_number(fork_root)
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless root
+
+          after_ref = after&.to_s&.strip
+          if after_ref && !after_ref.empty?
+            unless state.in_subtree?(fork_root, after_ref)
+              raise StepErrors::InvalidState, "Step #{after_ref} is outside scoped subtree #{fork_root}."
+            end
+
+            return [after_ref, as_child]
+          end
+
+          subtree = state.subtree_steps(fork_root)
+          last_subtree_step = subtree.last
+          return [fork_root, true] unless last_subtree_step
+          return [fork_root, true] if last_subtree_step.number == fork_root
+
+          [last_subtree_step.number, false]
+        end
+
         # Auto-complete parent steps when all their children are done.
         # Walks up the hierarchy marking parents as done, handling multi-level
         # completion in a single pass (grandparents become eligible when parents complete).
@@ -1782,9 +1832,9 @@ module Ace
             iterations += 1
             completed_any = false
 
-            # Find all pending/in_progress parent steps that have children
+            # Find all pending/active parent steps that have children
             eligible_parents = state.steps.select do |s|
-              (s.status == :pending || s.status == :in_progress) &&
+              (s.status == :pending || s.status == :active) &&
                 !completed_this_pass.include?(s.number)
             end
 

data/lib/ace/assign/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Assign
-    VERSION = '0.53.4'
+    VERSION = '0.55.0'
   end
 end

data/lib/ace/assign.rb

@@ -5,6 +5,7 @@ require "ace/support/config"
 require "ace/support/fs"
 require "ace/support/nav"
 require "ace/support/cli"
+require "ace/tmux"
 require "pathname"
 
 # CLI and commands