ocak 0.4.0 → 0.5.0

data/lib/ocak/pipeline_executor.rb

@@ -7,14 +7,18 @@ require_relative 'run_report'
 require_relative 'verification'
 require_relative 'planner'
 require_relative 'step_comments'
+require_relative 'state_management'
+require_relative 'step_execution'
+require_relative 'parallel_execution'
 
 module Ocak
   class PipelineExecutor
     include Verification
     include Planner
     include StepComments
-
-    StepContext = Struct.new(:issue_number, :idx, :role, :result, :state, :logger, :chdir)
+    include StateManagement
+    include StepExecution
+    include ParallelExecution
 
     attr_writer :issues
 
@@ -26,11 +30,13 @@ module Ocak
 
     def run_pipeline(issue_number, logger:, claude:, chdir: nil, skip_steps: [], complexity: 'full', # rubocop:disable Metrics/ParameterLists
                      steps: nil, verification_model: nil,
-                     post_start_comment: true, post_summary_comment: true)
+                     post_start_comment: true, post_summary_comment: true,
+                     skip_merge: false)
       @logger = logger
       @custom_steps = steps
       @verification_model = verification_model
       @post_summary_comment = post_summary_comment
+      @skip_merge = skip_merge
       chdir ||= @config.project_dir
       logger.info("=== Starting pipeline for issue ##{issue_number} (#{complexity}) ===")
 
@@ -120,55 +126,6 @@ module Ocak
       nil
     end
 
-    def collect_parallel_group(steps, start_idx)
-      group = []
-      idx = start_idx
-      while idx < steps.size
-        step = symbolize(steps[idx])
-        break unless step[:parallel]
-
-        group << [step, idx]
-        idx += 1
-      end
-      group
-    end
-
-    def run_parallel_group(group, issue_number, state, logger:, claude:, chdir:)
-      mutex = Mutex.new
-      threads = group.map do |step, idx|
-        Thread.new do
-          run_single_step(step, idx, issue_number, state, logger: logger, claude: claude,
-                                                          chdir: chdir, mutex: mutex)
-        rescue StandardError => e
-          logger.error("#{step[:role]} thread failed: #{e.message}")
-          nil
-        end
-      end
-
-      results = threads.map(&:value)
-      results.compact.find { |r| r.is_a?(Hash) && !r[:success] }
-    end
-
-    def run_single_step(step, idx, issue_number, state, logger:, claude:, chdir:, mutex: nil) # rubocop:disable Metrics/ParameterLists
-      role = step[:role].to_s
-      agent = step[:agent].to_s
-
-      return nil if handle_already_completed(idx, role, @skip_steps, logger)
-
-      reason = skip_reason(step, state)
-      if reason
-        logger.info("Skipping #{role} \u2014 #{reason}")
-        record_skipped_step(issue_number, state, idx, agent, role, reason)
-        return nil
-      end
-
-      result = execute_step(step, issue_number, state[:last_review_output], logger: logger, claude: claude,
-                                                                            chdir: chdir)
-      state[:report].record_step(index: idx, agent: agent, role: role, status: 'completed', result: result)
-      ctx = StepContext.new(issue_number, idx, role, result, state, logger, chdir)
-      record_step_result(ctx, mutex: mutex)
-    end
-
     def check_shutdown(state, logger)
       return false unless @shutdown_check&.call
 
@@ -176,121 +133,6 @@ module Ocak
       state[:interrupted] = true
     end
 
-    def handle_already_completed(idx, role, skip_steps, logger)
-      return false unless skip_steps.include?(idx)
-
-      logger.info("Skipping #{role} (already completed)")
-      true
-    end
-
-    def record_skipped_step(issue_number, state, idx, agent, role, reason)
-      post_step_comment(issue_number, "\u{23ED}\u{FE0F} **Skipping #{role}** \u2014 #{reason}")
-      state[:report].record_step(index: idx, agent: agent, role: role, status: 'skipped', skip_reason: reason)
-      state[:steps_skipped] += 1
-    end
-
-    def execute_step(step, issue_number, review_output, logger:, claude:, chdir:)
-      agent = step[:agent].to_s
-      role = step[:role].to_s
-      logger.info("--- Phase: #{role} (#{agent}) ---")
-      post_step_comment(issue_number, "\u{1F504} **Phase: #{role}** (#{agent})")
-      prompt = build_step_prompt(role, issue_number, review_output)
-      opts = { chdir: chdir }
-      opts[:model] = step[:model].to_s if step[:model]
-      claude.run_agent(agent.tr('_', '-'), prompt, **opts)
-    end
-
-    def record_step_result(ctx, mutex: nil)
-      sync(mutex) { accumulate_state(ctx) }
-      save_step_progress(ctx)
-      write_step_output(ctx.issue_number, ctx.idx, ctx.role, ctx.result.output)
-      post_step_completion_comment(ctx.issue_number, ctx.role, ctx.result)
-
-      check_step_failure(ctx) || check_cost_budget(ctx.state, ctx.logger)
-    end
-
-    def accumulate_state(ctx)
-      update_pipeline_state(ctx.role, ctx.result, ctx.state)
-      ctx.state[:completed_steps] << ctx.idx
-      ctx.state[:steps_run] += 1
-      ctx.state[:total_cost] += ctx.result.cost_usd.to_f
-      ctx.state[:step_results][ctx.role] = ctx.result
-    end
-
-    def sync(mutex, &)
-      if mutex
-        mutex.synchronize(&)
-      else
-        yield
-      end
-    end
-
-    def save_step_progress(ctx)
-      pipeline_state.save(ctx.issue_number,
-                          completed_steps: ctx.state[:completed_steps],
-                          worktree_path: ctx.chdir,
-                          branch: current_branch(ctx.chdir, logger: ctx.logger))
-    end
-
-    def write_step_output(issue_number, idx, agent, output)
-      return if output.to_s.empty?
-      return unless issue_number.to_s.match?(/\A\d+\z/)
-
-      safe_agent = agent.to_s.gsub(/[^a-zA-Z0-9_-]/, '')
-      dir = File.join(@config.project_dir, '.ocak', 'logs', "issue-#{issue_number}")
-      FileUtils.mkdir_p(dir)
-      File.write(File.join(dir, "step-#{idx}-#{safe_agent}.md"), output)
-    rescue StandardError => e
-      @logger&.debug("Step output write failed: #{e.message}")
-      nil
-    end
-
-    def check_step_failure(ctx)
-      return nil if ctx.result.success? || !%w[implement merge].include?(ctx.role)
-
-      ctx.logger.error("#{ctx.role} failed")
-      { success: false, phase: ctx.role, output: ctx.result.output }
-    end
-
-    def check_cost_budget(state, logger)
-      return nil unless @config.cost_budget && state[:total_cost] > @config.cost_budget
-
-      cost = format('%.2f', state[:total_cost])
-      budget = format('%.2f', @config.cost_budget)
-      logger.error("Cost budget exceeded ($#{cost}/$#{budget})")
-      { success: false, phase: 'budget', output: "Cost budget exceeded: $#{cost}" }
-    end
-
-    def skip_reason(step, state)
-      condition = step[:condition]
-
-      return 'audit found blocking issues' if step[:role].to_s == 'merge' && @config.audit_mode && state[:audit_blocked]
-      return 'manual review mode' if step[:role].to_s == 'merge' && @config.manual_review
-      return 'fast-track issue (simple complexity)' if step[:complexity] == 'full' && state[:complexity] == 'simple'
-      if condition == 'has_findings' && !state[:last_review_output]&.include?("\u{1F534}")
-        return 'no blocking findings from review'
-      end
-      return 'no fixes were made' if condition == 'had_fixes' && !state[:had_fixes]
-
-      nil
-    end
-
-    def update_pipeline_state(role, result, state)
-      case role
-      when 'review', 'verify', 'security', 'audit'
-        state[:last_review_output] = result.output
-        if role == 'audit'
-          state[:audit_output] = result.output
-          state[:audit_blocked] = !result.success? || result.output.to_s.match?(/BLOCK|🔴/)
-        end
-      when 'fix'
-        state[:had_fixes] = true
-        state[:last_review_output] = nil
-      when 'implement'
-        state[:last_review_output] = nil
-      end
-    end
-
     def run_final_verification(issue_number, logger:, claude:, chdir:)
       run_verification_with_retry(logger: logger, claude: claude, chdir: chdir,
                                   model: @verification_model) do |body|
@@ -298,22 +140,6 @@ module Ocak
       end
     end
 
-    def log_cost_summary(total_cost, logger)
-      return if total_cost.zero?
-
-      budget = @config.cost_budget
-      budget_str = budget ? " / $#{format('%.2f', budget)} budget" : ''
-      logger.info("Pipeline cost: $#{format('%.4f', total_cost)}#{budget_str}")
-    end
-
-    def save_report(report, issue_number, success:, failed_phase: nil)
-      report.finish(success: success, failed_phase: failed_phase)
-      report.save(issue_number, project_dir: @config.project_dir)
-    rescue StandardError => e
-      @logger&.debug("Report save failed: #{e.message}")
-      nil
-    end
-
     def pipeline_state
       @pipeline_state ||= PipelineState.new(log_dir: File.join(@config.project_dir, @config.log_dir))
     end

data/lib/ocak/pipeline_runner.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
+require_relative 'batch_processing'
 require_relative 'failure_reporting'
+require_relative 'instance_builders'
 require_relative 'merge_orchestration'
 require_relative 'pipeline_executor'
 require_relative 'process_registry'
+require_relative 'shutdown_handling'
 require_relative 'git_utils'
+require_relative 'issue_backend'
+require_relative 'local_merge_manager'
 require_relative 'reready_processor'
 
 module Ocak
   class PipelineRunner
+    include BatchProcessing
     include FailureReporting
+    include InstanceBuilders
     include MergeOrchestration
+    include ShutdownHandling
 
     attr_reader :registry
 
@@ -31,41 +39,23 @@ module Ocak
       @options[:single] ? run_single(@options[:single]) : run_loop
     end
 
-    def run_pipeline(issue_number, logger:, claude:, chdir: nil, skip_steps: [], complexity: 'full')
+    def run_pipeline(issue_number, logger:, claude:, chdir: nil, skip_steps: [], complexity: 'full', # rubocop:disable Metrics/ParameterLists
+                     skip_merge: false)
       @executor.run_pipeline(issue_number, logger: logger, claude: claude, chdir: chdir,
-                                           skip_steps: skip_steps, complexity: complexity)
-    end
-
-    def shutdown!
-      count = @active_mutex.synchronize { @shutdown_count += 1 }
-
-      if count >= 2
-        force_shutdown!
-      else
-        graceful_shutdown!
-      end
+                                           skip_steps: skip_steps, complexity: complexity,
+                                           skip_merge: skip_merge)
     end
 
     def shutting_down?
       @shutting_down
     end
 
-    def print_shutdown_summary
-      issues = @active_mutex.synchronize { @interrupted_issues.dup }
-      return if issues.empty?
-
-      warn "\nInterrupted issues:"
-      issues.each do |issue_number|
-        warn "  - Issue ##{issue_number}: ocak resume --issue #{issue_number}"
-      end
-    end
-
     private
 
     def run_single(issue_number)
       logger = build_logger(issue_number: issue_number)
       claude = build_claude(logger)
-      issues = IssueFetcher.new(config: @config)
+      issues = IssueBackend.build(config: @config)
       ensure_labels(issues, logger)
       @executor.issues = issues
       logger.info("Running single issue mode for ##{issue_number}")
@@ -84,14 +74,14 @@ module Ocak
       elsif result[:success]
         handle_single_success(issue_number, result, logger: logger, claude: claude, issues: issues)
       else
-        report_pipeline_failure(issue_number, result, issues: issues, config: @config)
+        report_pipeline_failure(issue_number, result, issues: issues, config: @config, logger: logger)
         logger.error("Issue ##{issue_number} failed at phase: #{result[:phase]}")
       end
     end
 
     def run_loop
       logger = build_logger
-      issues = IssueFetcher.new(config: @config, logger: logger)
+      issues = IssueBackend.build(config: @config, logger: logger)
       ensure_labels(issues, logger)
       @executor.issues = issues
       cleanup_stale_worktrees(logger)
@@ -122,101 +112,6 @@ module Ocak
       end
     end
 
-    def process_issues(ready_issues, logger:, issues:)
-      if ready_issues.size > @config.max_issues_per_run
-        logger.warn("Capping to #{@config.max_issues_per_run} issues (found #{ready_issues.size})")
-        ready_issues = ready_issues.first(@config.max_issues_per_run)
-      end
-
-      claude = build_claude(logger)
-      batches = @executor.plan_batches(ready_issues, logger: logger, claude: claude)
-
-      batches.each_with_index do |batch, idx|
-        batch_issues = batch['issues'][0...@config.max_parallel]
-        logger.info("Running batch #{idx + 1}/#{batches.size} (#{batch_issues.size} issues)")
-
-        if @options[:dry_run]
-          batch_issues.each { |i| logger.info("[DRY RUN] Would process issue ##{i['number']}: #{i['title']}") }
-          next
-        end
-
-        run_batch(batch_issues, logger: logger, issues: issues)
-      end
-    end
-
-    def run_batch(batch_issues, logger:, issues:)
-      worktrees = WorktreeManager.new(config: @config, logger: logger)
-
-      threads = batch_issues.map do |issue|
-        Thread.new { process_one_issue(issue, worktrees: worktrees, issues: issues) }
-      end
-      results = threads.map(&:value)
-
-      unless @shutting_down
-        merger = MergeManager.new(
-          config: @config, claude: build_claude(logger), logger: logger, issues: issues, watch: @watch_formatter
-        )
-        results.select { |r| r[:success] }.each do |result|
-          merge_completed_issue(result, merger: merger, issues: issues, logger: logger)
-        end
-      end
-
-      results.each do |result|
-        next unless result[:worktree]
-        next if result[:interrupted]
-
-        worktrees.remove(result[:worktree])
-      rescue StandardError => e
-        logger.warn("Failed to clean worktree for ##{result[:issue_number]}: #{e.message}")
-      end
-
-      programming_error = results.find { |r| r[:programming_error] }&.dig(:programming_error)
-      raise programming_error if programming_error
-    end
-
-    def process_one_issue(issue, worktrees:, issues:)
-      issue_number = issue['number']
-      logger = build_logger(issue_number: issue_number)
-      claude = build_claude(logger)
-      worktree = nil
-
-      @active_mutex.synchronize do
-        @active_issues << issue_number
-      end
-      issues.transition(issue_number, from: @config.label_ready, to: @config.label_in_progress)
-      worktree = worktrees.create(issue_number, setup_command: @config.setup_command)
-      logger.info("Created worktree at #{worktree.path} (branch: #{worktree.branch})")
-
-      complexity = @options[:fast] ? 'simple' : issue.fetch('complexity', 'full')
-      result = run_pipeline(issue_number, logger: logger, claude: claude, chdir: worktree.path,
-                                          complexity: complexity)
-
-      build_issue_result(result, issue_number: issue_number, worktree: worktree, issues: issues,
-                                 logger: logger)
-    rescue StandardError => e
-      handle_process_error(e, issue_number: issue_number, logger: logger, issues: issues)
-      result = { issue_number: issue_number, success: false, worktree: worktree, error: e.message }
-      # NameError includes NoMethodError
-      result[:programming_error] = e if e.is_a?(NameError) || e.is_a?(TypeError)
-      result
-    ensure
-      @active_mutex.synchronize { @active_issues.delete(issue_number) }
-    end
-
-    def build_issue_result(result, issue_number:, worktree:, issues:, logger: nil)
-      if result[:interrupted]
-        handle_interrupted_issue(issue_number, worktree&.path, result[:phase],
-                                 logger: logger || build_logger(issue_number: issue_number), issues: issues)
-        { issue_number: issue_number, success: false, worktree: worktree, interrupted: true }
-      elsif result[:success]
-        { issue_number: issue_number, success: true, worktree: worktree,
-          audit_blocked: result[:audit_blocked], audit_output: result[:audit_output] }
-      else
-        report_pipeline_failure(issue_number, result, issues: issues, config: @config)
-        { issue_number: issue_number, success: false, worktree: worktree }
-      end
-    end
-
     def process_reready_prs(logger:, issues:)
       reready = issues.fetch_reready_prs
       return if reready.empty?
@@ -231,65 +126,5 @@ module Ocak
         processor.process(pr)
       end
     end
-
-    def cleanup_stale_worktrees(logger)
-      worktrees = WorktreeManager.new(config: @config, logger: logger)
-      removed = worktrees.clean_stale
-      removed.each { |path| logger.info("Cleaned stale worktree: #{path}") }
-    rescue StandardError => e
-      logger.warn("Stale worktree cleanup failed: #{e.message}")
-    end
-
-    def ensure_labels(issues, logger)
-      issues.ensure_labels(@config.all_labels)
-    rescue StandardError => e
-      logger.warn("Failed to ensure labels: #{e.message}")
-    end
-
-    def build_logger(issue_number: nil)
-      PipelineLogger.new(log_dir: File.join(@config.project_dir, @config.log_dir),
-                         issue_number: issue_number, log_level: @options.fetch(:log_level, :normal))
-    end
-
-    def build_claude(logger)
-      ClaudeRunner.new(config: @config, logger: logger, watch: @watch_formatter, registry: @registry)
-    end
-
-    def graceful_shutdown!
-      @shutting_down = true
-      warn "\nGraceful shutdown initiated — finishing current agent step(s)..."
-    end
-
-    def force_shutdown!
-      @shutting_down = true
-      warn "\nForce shutdown — killing active processes..."
-      @registry.kill_all
-    end
-
-    def handle_process_error(error, issue_number:, logger:, issues:)
-      logger.error("Unexpected #{error.class}: #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
-      logger.debug("Full backtrace:\n#{error.backtrace&.join("\n")}")
-      issues.transition(issue_number, from: @config.label_in_progress, to: @config.label_failed)
-      begin
-        issues.comment(issue_number, "Unexpected #{error.class}: #{error.message}")
-      rescue StandardError
-        nil
-      end
-    end
-
-    def handle_interrupted_issue(issue_number, worktree_path, step_name, logger:, issues:)
-      if worktree_path
-        GitUtils.commit_changes(chdir: worktree_path,
-                                message: "wip: pipeline interrupted after step #{step_name} for issue ##{issue_number}",
-                                logger: logger)
-      end
-      issues&.transition(issue_number, from: @config.label_in_progress, to: @config.label_ready)
-      issues&.comment(issue_number,
-                      "\u{26A0}\u{FE0F} Pipeline interrupted after #{step_name}. " \
-                      "Resume with `ocak resume --issue #{issue_number}`.")
-      @active_mutex.synchronize { @interrupted_issues << issue_number }
-    rescue StandardError => e
-      logger.warn("Failed to handle interrupted issue ##{issue_number}: #{e.message}")
-    end
   end
 end

data/lib/ocak/planner.rb

@@ -30,7 +30,7 @@ module Ocak
       issue_json = JSON.generate(issues.map { |i| { number: i['number'], title: i['title'] } })
       result = claude.run_agent(
         'planner',
-        "Analyze these issues and output parallelization batches as JSON:\n\n#{issue_json}"
+        "Analyze these issues and output parallelization batches as JSON:\n\n<issue_data>\n#{issue_json}\n</issue_data>"
       )
 
       unless result.success?

data/lib/ocak/project_key.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Ocak
+  module ProjectKey
+    class NoRemoteError < StandardError; end
+
+    # Resolve owner/repo from git remote origin.
+    # Returns a string like "owner/repo".
+    # Raises NoRemoteError if no remote or URL is unparseable.
+    def self.resolve(dir = Dir.pwd)
+      url = fetch_remote_url(dir)
+      parse_url(url)
+    end
+
+    def self.fetch_remote_url(dir)
+      stdout, _stderr, status = Open3.capture3('git', 'remote', 'get-url', 'origin', chdir: dir)
+      raise NoRemoteError, "No git remote 'origin' found in #{dir}" unless status.success?
+
+      stdout.strip
+    end
+    private_class_method :fetch_remote_url
+
+    def self.parse_url(url)
+      # Matches both SSH and HTTPS patterns:
+      #   git@github.com:owner/repo.git     → owner, repo
+      #   https://github.com/owner/repo.git → owner, repo
+      #   https://github.com/owner/repo     → owner, repo
+      if (match = url.match(%r{[/:]([\w.-]+)/([\w.-]+?)(?:\.git)?$}))
+        "#{match[1]}/#{match[2]}"
+      else
+        raise NoRemoteError, "Cannot parse owner/repo from remote URL: #{url}"
+      end
+    end
+    private_class_method :parse_url
+  end
+end

data/lib/ocak/reready_processor.rb

@@ -3,9 +3,12 @@
 require 'open3'
 require 'shellwords'
 require_relative 'git_utils'
+require_relative 'command_runner'
 
 module Ocak
   class RereadyProcessor
+    include CommandRunner
+
     def initialize(config:, logger:, claude:, issues:, watch: nil)
       @config = config
       @logger = logger
@@ -61,17 +64,14 @@ module Ocak
     end
 
     def checkout_pr_branch(branch_name)
-      _, _, fetch_status = Open3.capture3('git', 'fetch', 'origin', branch_name,
-                                          chdir: @config.project_dir)
-      return false unless fetch_status.success?
+      fetch_result = run_git('fetch', 'origin', branch_name, chdir: @config.project_dir)
+      return false unless fetch_result.success?
 
-      _, _, checkout_status = Open3.capture3('git', 'checkout', branch_name,
-                                             chdir: @config.project_dir)
-      return false unless checkout_status.success?
+      checkout_result = run_git('checkout', branch_name, chdir: @config.project_dir)
+      return false unless checkout_result.success?
 
-      _, _, pull_status = Open3.capture3('git', 'pull', '--rebase', 'origin', branch_name,
-                                         chdir: @config.project_dir)
-      pull_status.success?
+      pull_result = run_git('pull', '--rebase', 'origin', branch_name, chdir: @config.project_dir)
+      pull_result.success?
     end
 
     def run_feedback_loop(feedback)
@@ -131,8 +131,8 @@ module Ocak
       )
       @logger.warn('Proceeding to push without new commit') unless committed
 
-      _, _, push_status = Open3.capture3('git', 'push', '--force-with-lease', chdir: @config.project_dir)
-      push_status.success?
+      push_result = run_git('push', '--force-with-lease', chdir: @config.project_dir)
+      push_result.success?
     end
 
     def cleanup

data/lib/ocak/run_report.rb

@@ -50,6 +50,9 @@ module Ocak
       path = File.join(dir, "issue-#{issue_number}-#{timestamp}.json")
       File.write(path, JSON.pretty_generate(to_h(issue_number)))
       path
+    rescue SystemCallError => e
+      warn("Failed to save report to #{path}: #{e.message}")
+      nil
     end
 
     def to_h(issue_number)
@@ -75,8 +78,8 @@ module Ocak
 
       Dir.glob(File.join(dir, 'issue-*.json')).filter_map do |path|
         JSON.parse(File.read(path), symbolize_names: true)
-      rescue JSON::ParserError => e
-        warn("Skipping malformed report #{File.basename(path)}: #{e.message}")
+      rescue JSON::ParserError, SystemCallError => e
+        warn("Skipping report #{File.basename(path)}: #{e.message}")
         nil
       end
     end

data/lib/ocak/shutdown_handling.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Ocak
+  # Shutdown orchestration logic — graceful/force shutdown, interrupt/error handling, summary.
+  # Extracted from PipelineRunner to reduce file size.
+  module ShutdownHandling
+    def shutdown!
+      count = @active_mutex.synchronize { @shutdown_count += 1 }
+
+      if count >= 2
+        force_shutdown!
+      else
+        graceful_shutdown!
+      end
+    end
+
+    def print_shutdown_summary
+      issues = @active_mutex.synchronize { @interrupted_issues.dup }
+      return if issues.empty?
+
+      warn "\nInterrupted issues:"
+      issues.each do |issue_number|
+        warn "  - Issue ##{issue_number}: ocak resume --issue #{issue_number}"
+      end
+    end
+
+    private
+
+    def graceful_shutdown!
+      @shutting_down = true
+      warn "\nGraceful shutdown initiated — finishing current agent step(s)..."
+    end
+
+    def force_shutdown!
+      @shutting_down = true
+      warn "\nForce shutdown — killing active processes..."
+      @registry.kill_all
+    end
+
+    def handle_process_error(error, issue_number:, logger:, issues:)
+      logger.error("Unexpected #{error.class}: #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
+      logger.debug("Full backtrace:\n#{error.backtrace&.join("\n")}")
+      issues.transition(issue_number, from: @config.label_in_progress, to: @config.label_failed)
+      begin
+        issues.comment(issue_number, "Unexpected #{error.class}: #{error.message}")
+      rescue StandardError => e
+        logger&.debug("Comment posting failed: #{e.message}")
+        nil
+      end
+    end
+
+    def handle_interrupted_issue(issue_number, worktree_path, step_name, logger:, issues:)
+      if worktree_path
+        GitUtils.commit_changes(chdir: worktree_path,
+                                message: "wip: pipeline interrupted after step #{step_name} for issue ##{issue_number}",
+                                logger: logger)
+      end
+      issues&.transition(issue_number, from: @config.label_in_progress, to: @config.label_ready)
+      issues&.comment(issue_number,
+                      "\u{26A0}\u{FE0F} Pipeline interrupted after #{step_name}. " \
+                      "Resume with `ocak resume --issue #{issue_number}`.")
+      @active_mutex.synchronize { @interrupted_issues << issue_number }
+    rescue StandardError => e
+      logger.warn("Failed to handle interrupted issue ##{issue_number}: #{e.message}")
+    end
+  end
+end