snitcher_reports 0.2.0

data/lib/snitcher/sources/clickup.rb

@@ -0,0 +1,467 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require 'time'
+require_relative 'clickup/working_hours_filter'
+require_relative 'clickup/archived_lists'
+
+module Snitcher
+  module Sources
+    # rubocop:disable-next Metrics/ClassLength -- Length due to required YARD docs and helper methods
+    class ClickUp < Source
+      include WorkingHoursFilter
+      include ArchivedLists
+
+      BASE_URL = 'https://api.clickup.com/api/v2'
+      PAGINATION_MAX_PAGES = 10 # Safety limit to prevent infinite loops
+      # Runaway guard for the archived-list walk, not a routine cut: the API returns lists
+      # in its own order, so which tasks a truncated walk drops is arbitrary. A real
+      # workspace measured 66 archived lists.
+      ARCHIVED_LISTS_MAX = 100
+      MS_PER_SECOND = 1_000
+      # ClickUp status type for user-defined workflow statuses.
+      # Status types are language-independent (unlike status names).
+      # 'custom' covers all statuses between 'open' (to-do) and 'closed' (done),
+      # which makes it the right proxy for "in progress" time regardless of locale.
+      CUSTOM_STATUS_TYPE = 'custom'
+      SECONDS_PER_MINUTE = 60
+      # ClickUp's bulk_time_in_status endpoint serialises task IDs as repeated query params.
+      # 100 IDs per batch keeps URLs well under typical server/proxy limits (~8 KB).
+      BULK_TASK_IDS_BATCH_SIZE = 100
+
+      def initialize(config = {})
+        super
+        # Use presence check to handle empty strings from ENV
+        @api_token = Source.presence(config[:api_token]) || Source.env('CLICKUP_API_TOKEN')
+        raw_team_id = Source.presence(config[:team_id]) || Source.env('CLICKUP_TEAM_ID')
+        # Validate team_id to prevent URL path injection
+        @team_id = raw_team_id ? Validators.validate_id!(raw_team_id, name: 'team_id') : nil
+        # Status names to filter for closed tasks (from .snitcher.yml or default)
+        @done_statuses = config[:done_statuses] || ['closed']
+        # Space names from config; resolved to IDs at init time (one API call).
+        # Stored as a Set for O(1) membership checks (see filter_time_entries convention).
+        # Faraday::Error is rescued here so a ClickUp API outage does not crash the entire
+        # CLI run — only this source is degraded, Jira/Linear/Git continue normally.
+        space_names = config[:spaces] || []
+        @space_ids = if space_names.any? && available?
+                       begin
+                         ids = resolve_space_ids(space_names)
+                         if ids.empty?
+                           warn '[clickup] Warning: none of the configured spaces could be resolved; ' \
+                                'fetching from all spaces'
+                         end
+                         Set.new(ids)
+                       rescue Faraday::Error => e
+                         warn "[clickup] Warning: could not resolve space names (#{e.message}); " \
+                              'fetching from all spaces'
+                         Set.new
+                       end
+                     else
+                       Set.new
+                     end
+      end
+
+      # Discover all statuses across ClickUp spaces for the configured workspace.
+      # Uses language-independent `type` field to categorize statuses.
+      # Currently unused in fetch flow — kept for potential config discovery use.
+      #
+      # @param config [Hash] optional config overrides
+      # @return [Hash] status discovery result
+      def self.discover_statuses(config = {})
+        instance = new(config)
+        return { error: 'ClickUp not configured' } unless instance.available?
+
+        instance.send(:fetch_space_statuses)
+      end
+
+      # Discover all ClickUp spaces for the configured workspace.
+      # Used during `snitcher init` to present available spaces to the user.
+      #
+      # @param config [Hash] optional config overrides (api_token:, team_id:)
+      # @return [Array<Hash>, Hash] array of {id:, name:} hashes, or {error: "..."} on failure
+      def self.discover_spaces(config = {})
+        instance = new(config)
+        return { error: 'ClickUp not configured' } unless instance.available?
+
+        spaces = instance.send(:fetch_spaces)
+        spaces.map { |s| { id: s['id'], name: s['name'] } }
+      rescue StandardError => e
+        { error: "Failed to fetch ClickUp spaces: #{e.message}" }
+      end
+
+      def source_name
+        :clickup
+      end
+
+      def available?
+        !!(@api_token && @team_id)
+      end
+
+      def unavailable_reason
+        missing = []
+        missing << 'CLICKUP_API_TOKEN' if @api_token.nil?
+        missing << 'CLICKUP_TEAM_ID' if @team_id.nil?
+        "#{missing.join(', ')} #{missing.one? ? 'is' : 'are'} not set"
+      end
+
+      def fetch(user_email:, since:, until_time:)
+        return [] unless available?
+
+        user_id = find_user_id(primary_email(user_email))
+        return [] unless user_id
+
+        tasks = fetch_tasks(user_id: user_id, since: since, until_time: until_time)
+        time_entries = fetch_time_entries(user_id: user_id, since: since, until_time: until_time)
+
+        # Three-tier strategy for resolving task time:
+        # Tier 1 (:worklog)    — time entries API sum > 0
+        # Tier 2 (:worklog)    — task's time_spent field > 0 (when no tracked entries)
+        # Tier 3 (:calculated) — status history fallback via bulk_time_in_status API
+        # Tasks without Tier 1/2 data collect their IDs in no_time_ids for Tier 3 resolution.
+
+        time_by_task = time_entries.group_by { |te| te.dig('task', 'id') }
+        results = []
+        no_time_ids = []
+        tasks.each do |task|
+          task_time_entries = time_by_task[task['id']] || []
+          # Running timers are already filtered out in fetch_time_entries; .abs is a defensive guard
+          # in case any slip through. ClickUp durations are in milliseconds.
+          total_time_ms = task_time_entries.sum { |te| te['duration'].to_i.abs }
+
+          # Use time tracking if available, otherwise use task's time_spent.
+          # ClickUp timestamps and durations are in milliseconds.
+          time_seconds = if total_time_ms.positive?
+                           total_time_ms / MS_PER_SECOND
+                         elsif task['time_spent'].to_i.positive?
+                           task['time_spent'].to_i / MS_PER_SECOND
+                         end
+
+          if time_seconds
+            results << build_task_work_item(task, time_spent_seconds: time_seconds, time_source: :worklog)
+          else
+            no_time_ids << task['id']
+          end
+        end
+
+        apply_status_time_fallback(results, no_time_ids, tasks)
+        results
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: BASE_URL) do |f|
+          f.request :json
+          # Without this an expired token answers every call with a body that simply lacks
+          # the expected key, `body['tasks'] || []` turns it into "no work", and the source
+          # reports a quiet week instead of an outage — the failure mode Jira's client
+          # documents at length (jira/client.rb:18-24). Registered before :retry so it nests
+          # outside it: the other way round a 429/5xx becomes an exception before retry can
+          # read the status, and retry_statuses never fires. Every ClickUp call here is a
+          # GET, so faraday-retry's idempotent-only default needs no widening.
+          f.response :raise_error
+          f.request :retry, max: 3, interval: 0.5, retry_statuses: [429, 500, 502, 503, 504]
+          f.response :json
+          f.headers['Authorization'] = @api_token
+          f.options.timeout = 15
+          f.options.open_timeout = 5
+        end
+      end
+
+      def find_user_id(email)
+        @user_id_cache ||= {}
+        return @user_id_cache[email] if @user_id_cache.key?(email)
+
+        response = connection.get("team/#{@team_id}")
+        members = response.body.dig('team', 'members') || []
+
+        member = members.find { |m| m.dig('user', 'email')&.downcase == email.downcase }
+        @user_id_cache[email] = member&.dig('user', 'id')
+      end
+
+      # The two passes overlap only by accident, but a task ClickUp reports through both
+      # would otherwise be counted twice, the way a repeated page used to be.
+      def fetch_tasks(user_id:, since:, until_time:)
+        all_tasks = paginate_tasks(user_id: user_id, since: since, until_time: until_time)
+        seen_task_ids = Set.new(all_tasks.map { |task| task['id'] })
+
+        # A task with no id is dropped here too, for the reason #paginate_tasks drops it:
+        # it cannot be told apart from another id-less task, and admitting it on this path
+        # alone would make a task's presence depend on which pass found it.
+        # add?, not include?: the assignee test runs first, so a task rejected on it never
+        # enters the set.
+        from_archived = archived_tasks(since: since, until_time: until_time).select do |task|
+          task['id'] && assigned_to?(task, user_id) && seen_task_ids.add?(task['id'])
+        end
+
+        filter_tasks_by_date(all_tasks + from_archived, since: since, until_time: until_time)
+      end
+
+      def paginate_tasks(user_id:, since:, until_time:)
+        all_tasks = []
+        seen_task_ids = Set.new
+        page = 0
+
+        loop do
+          response = connection.get("team/#{@team_id}/task") do |req|
+            req.options.params_encoder = Faraday::FlatParamsEncoder
+            # No statuses[] filter: lists and folders can override space-level statuses
+            # via the override_statuses flag, introducing custom status names that differ
+            # from space-level ones. Filtering by status name across a workspace is therefore
+            # unreliable without fetching all lists/folders to build a complete status map.
+            # date_done_gt/lt is the correct ClickUp filter for completion date (Unix ms).
+            # date_closed_gt/lt is not a valid API parameter and is silently ignored.
+            # Client-side filter in filter_tasks_by_date is the authoritative guard.
+            req.params = {
+              'assignees[]' => user_id,
+              'date_done_gt' => (since.to_f * MS_PER_SECOND).to_i,
+              'date_done_lt' => (until_time.to_f * MS_PER_SECOND).to_i,
+              'include_closed' => true,
+              'page' => page
+            }
+            req.params['space_ids[]'] = @space_ids.to_a if @space_ids.any?
+          end
+
+          tasks = response.body['tasks'] || []
+          break if tasks.empty?
+
+          # Past the last page the API repeats it rather than answering with an empty list —
+          # the same behaviour #filter_time_entries dedups against. Without this every repeat
+          # was concatenated whole, so one task could arrive PAGINATION_MAX_PAGES times and
+          # its hours were counted that many times over. A page carrying nothing new is that
+          # repeat, and it is also the only end-of-listing signal the endpoint gives.
+          # A task with no id is dropped rather than deduped, so it can't collapse with an
+          # unrelated id-less task and silently under-count the other one's hours.
+          fresh = tasks.select { |task| task['id'] && seen_task_ids.add?(task['id']) }
+          break if fresh.empty?
+
+          all_tasks.concat(fresh)
+          page += 1
+          break if page >= PAGINATION_MAX_PAGES
+        end
+
+        all_tasks
+      end
+
+      # Filters tasks to only those closed within the requested range.
+      # Defensive guard against tasks with no date_closed (e.g. not yet closed) slipping through.
+      def filter_tasks_by_date(tasks, since:, until_time:)
+        since_ms = (since.to_f * MS_PER_SECOND).to_i
+        until_ms = (until_time.to_f * MS_PER_SECOND).to_i
+
+        tasks.select do |t|
+          closed_ms = t['date_closed'].to_i
+          closed_ms.positive? && closed_ms > since_ms && closed_ms < until_ms
+        end
+      end
+
+      # Time entries are fetched workspace-wide. The API supports a singular space_id param
+      # but not space_ids[], so filtering by multiple spaces would require one request per
+      # space. Instead we rely on the task-ID join in #fetch: tasks are already scoped to
+      # the configured spaces via space_ids[], so time entries for other spaces are simply
+      # never matched and are discarded. Results are correct; the only cost is fetching
+      # more entries than needed in large workspaces.
+      def fetch_time_entries(user_id:, since:, until_time:)
+        all_entries = []
+        seen_entry_ids = Set.new
+        page = 0
+
+        loop do
+          response = connection.get("team/#{@team_id}/time_entries") do |req|
+            req.params = {
+              'assignee' => user_id,
+              # ClickUp timestamps are in milliseconds
+              'start_date' => (since.to_f * MS_PER_SECOND).to_i,
+              'end_date' => (until_time.to_f * MS_PER_SECOND).to_i,
+              'page' => page
+            }
+          end
+
+          entries = response.body['data'] || []
+          break if entries.empty?
+
+          # Same repeated-last-page behaviour #paginate_tasks guards against: stopping on a
+          # page with nothing new avoids walking every remaining page on short result sets.
+          fresh = entries.select { |te| seen_entry_ids.add?(te['id']) }
+          break if fresh.empty?
+
+          all_entries.concat(fresh)
+          page += 1
+          break if page >= PAGINATION_MAX_PAGES
+        end
+
+        filter_time_entries(all_entries, user_id)
+      end
+
+      # Dedup (API repeats last page), drop running timers, keep only this user's entries.
+      # Single-pass to avoid three intermediate arrays.
+      def filter_time_entries(entries, user_id)
+        seen = Set.new
+        entries.each_with_object([]) do |te, result|
+          next unless seen.add?(te['id'])
+          next if te['duration'].to_i.negative?
+          next unless te.dig('user', 'id').to_s == user_id.to_s
+
+          result << te
+        end
+      end
+
+      def task_metadata(task)
+        { status: task.dig('status', 'status'), priority: task.dig('priority', 'priority'),
+          list: task.dig('list', 'name'), space: task.dig('space', 'name'),
+          tags: task['tags']&.map { |t| t['name'] } }
+      end
+
+      # Fetches cumulative time-in-status for multiple tasks.
+      # Batches requests to avoid URL length limits. Requires paid ClickUp plan.
+      # Partial results from successful batches are preserved even if a later batch fails.
+      # On free plans, the API returns HTTP 403; raise_error turns that into a
+      # Faraday::Error before response.success? is ever evaluated, and it's the rescue
+      # below — not the guard — that keeps the batch loop going.
+      # See: https://help.clickup.com/hc/en-us/articles/6304185469719
+      def fetch_bulk_time_in_status(task_ids)
+        return {} if task_ids.empty?
+
+        result = {}
+        task_ids.each_slice(BULK_TASK_IDS_BATCH_SIZE) do |batch|
+          response = connection.get('task/bulk_time_in_status/task_ids') do |req|
+            # FlatParamsEncoder serialises the array as repeated params:
+            # task_ids=id1&task_ids=id2 — the format expected by ClickUp's bulk endpoint.
+            req.options.params_encoder = Faraday::FlatParamsEncoder
+            req.params = { 'task_ids' => batch }
+          end
+          next unless response.body.is_a?(Hash)
+
+          result.merge!(response.body)
+        rescue Faraday::Error => e
+          warn "[clickup] bulk_time_in_status batch failed: #{e.message}"
+        end
+        result
+      end
+
+      # Applies status-time fallback for tasks with no tracked time (Tier 3).
+      # Requires paid ClickUp plan; on free plans tasks are added with nil time.
+      #
+      # @param results [Array<WorkItem>] items already built (with time)
+      # @param no_time_ids [Array<String>] task IDs that had no time data
+      # @param tasks [Array<Hash>] all fetched task hashes (for metadata)
+      def apply_status_time_fallback(results, no_time_ids, tasks)
+        return if no_time_ids.empty?
+
+        status_data = fetch_bulk_time_in_status(no_time_ids)
+        tasks_by_id = tasks.to_h { |t| [t['id'], t] }
+        no_time_ids.each do |task_id|
+          task = tasks_by_id[task_id]
+          next unless task
+
+          closed_at = parse_closed_at(task)
+          seconds = calculate_time_from_status_history(
+            status_data.dig(task_id, 'status_history'),
+            task_closed_at: closed_at
+          )
+          results << build_task_work_item(
+            task,
+            time_spent_seconds: seconds.positive? ? seconds : nil,
+            time_source: seconds.positive? ? :calculated : nil,
+            closed_at: closed_at
+          )
+        end
+      end
+
+      # @param task [Hash] ClickUp task hash
+      # @return [Time, nil] task close time, or nil if task has no valid date_closed
+      def parse_closed_at(task)
+        # date_closed "0" or "" means reopened/not-closed; treat as nil.
+        ms = task['date_closed'].to_i
+        ms.positive? ? Time.at(ms / MS_PER_SECOND) : nil
+      end
+
+      # @param task [Hash] ClickUp task hash
+      # @param time_spent_seconds [Integer, nil] calculated time in seconds
+      # @param time_source [Symbol, nil] how time was determined (:worklog, :calculated)
+      # @param closed_at [Time, nil] pre-parsed close time; avoids re-parsing date_closed
+      #   when caller already computed it (e.g. apply_status_time_fallback)
+      def build_task_work_item(task, time_spent_seconds:, time_source:, closed_at: nil)
+        build_work_item(
+          external_id: task['id'],
+          title: task['name'],
+          completed_at: closed_at || parse_closed_at(task),
+          time_spent_seconds: time_spent_seconds,
+          time_source: time_source,
+          url: task['url'],
+          metadata: task_metadata(task)
+        )
+      end
+
+      # Fetches all spaces for the configured team from the ClickUp API.
+      # Result is cached per-instance to avoid duplicate API calls within a single run
+      # (e.g. resolve_space_ids at init and fetch_space_statuses during fetch).
+      # Raises on network or API errors — callers are responsible for rescue.
+      #
+      # @return [Array<Hash>] raw space hashes from the ClickUp API
+      def fetch_spaces
+        @fetch_spaces ||= begin
+          response = connection.get("team/#{@team_id}/space", { archived: false })
+          response.body['spaces'] || []
+        end
+      end
+
+      # Resolves an array of space names to ClickUp space IDs via a single API call.
+      # Warns and skips any name that does not match a known space (case-sensitive).
+      #
+      # @param space_names [Array<String>] display names from config
+      # @return [Array<String>] resolved space IDs; may be shorter than space_names
+      def resolve_space_ids(space_names)
+        spaces = fetch_spaces
+        name_to_id = spaces.each_with_object({}) do |s, h|
+          validated_id = Validators.validate_id!(s['id'], name: 'space_id')
+          h[s['name']] = validated_id
+        rescue Validators::ValidationError => e
+          warn "[clickup] Warning: skipping space with invalid ID (#{e.message})"
+        end
+
+        space_names.filter_map do |name|
+          id = name_to_id[name]
+          warn "[clickup] Warning: unknown space '#{name}' ignored" unless id
+          id
+        end
+      end
+
+      # Fetches and categorizes statuses from ClickUp spaces by language-independent type:
+      # 'closed' → done, 'custom' → in_progress, 'open' → open.
+      # When @space_ids is non-empty, only statuses from those spaces are included.
+      #
+      # @return [Hash] categorized statuses or error
+      def fetch_space_statuses
+        spaces = fetch_spaces
+        spaces = spaces.select { |s| @space_ids.include?(s['id']) } if @space_ids.any?
+
+        all_statuses = spaces.flat_map { |space| space['statuses'] || [] }
+
+        # Single-pass categorization for performance (O(n) instead of O(4n))
+        categorized = { done: Set.new, in_progress: Set.new, open: Set.new, all: [] }
+        all_statuses.each do |s|
+          status_name = s['status']
+          categorized[:all] << { name: status_name, type: s['type'], color: s['color'] }
+
+          case s['type']
+          when 'closed' then categorized[:done] << status_name
+          when 'custom' then categorized[:in_progress] << status_name
+          when 'open'   then categorized[:open] << status_name
+          end
+        end
+
+        {
+          done_statuses: categorized[:done].to_a,
+          in_progress_statuses: categorized[:in_progress].to_a,
+          open_statuses: categorized[:open].to_a,
+          all_statuses: categorized[:all].uniq
+        }
+      rescue StandardError => e
+        { error: "Failed to fetch ClickUp statuses: #{e.message}" }
+      end
+    end
+  end
+end

data/lib/snitcher/sources/git/command_runner.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Snitcher
+  module Sources
+    class Git < Source
+      # Subprocess transport for the Git source.
+      #
+      # Extracted from Git for the same reason Jira::Client was (jira/client.rb): the
+      # source stays about interpreting commits, and the part that spawns processes can
+      # be tested against real ones.
+      #
+      # Two rules, and both exist because the alternative is a report that lies:
+      #
+      # 1. A git that exits non-zero raises. Returning an empty string instead would make
+      #    "nobody committed this week" and "the checkout is broken" produce the same
+      #    report — zero items, nothing in Orchestrator#failed_sources, a silent console.
+      #    Callers that can genuinely absorb a failure ask for it by name via
+      #    #output_or_nil.
+      # 2. A git that hangs is killed. Every command run here is a local read; the ones
+      #    that do not return in milliseconds (an index.lock held by a crashed process, an
+      #    unresponsive network filesystem, a credential helper prompting a terminal that
+      #    is not there) do not return at all, and one of them is enough to wedge a whole
+      #    batch of reports.
+      #
+      # @api private
+      class CommandRunner
+        # A git command that exited non-zero.
+        class CommandError < Error; end
+
+        # A git command that overran the timeout and was killed. Separate from
+        # CommandError so #output_or_nil can absorb the one without absorbing the other.
+        class TimeoutError < Error; end
+
+        # Seconds a single git command may run before it is killed. Generous enough for a
+        # `git log` over a large history on a cold cache, short enough that a hung command
+        # costs a report rather than the day. Override with sources.git.timeout.
+        DEFAULT_TIMEOUT_SECONDS = 30
+
+        # How long a killed git gets between the TERM and the KILL. TERM first so it can
+        # drop its index.lock; KILL because the point of a timeout is that it ends.
+        TERMINATE_GRACE_SECONDS = 2
+
+        # How much of git's complaint is quoted in an error message. The cause is in the
+        # first line or two; the rest is advice for a human at a terminal.
+        MAX_STDERR_LINES = 3
+        MAX_STDERR_CHARS = 300
+
+        # @param timeout_seconds [Numeric, String, nil] raw sources.git.timeout value
+        def initialize(repo_path:, timeout_seconds: nil)
+          @repo_path = repo_path
+          @timeout_seconds = normalize_timeout(timeout_seconds)
+        end
+
+        # Runs a git command and returns its stdout.
+        #
+        # @param args [Array<String>] arguments after the `git` program name
+        # @return [String] stdout
+        # @raise [CommandError] git exited non-zero
+        # @raise [TimeoutError] git had to be killed
+        def output(args)
+          cmd = ['git', *args]
+          stdout, stderr, status = run(cmd)
+          return stdout if status.success?
+
+          raise CommandError, failure_message(cmd: cmd, status: status, stderr: stderr)
+        end
+
+        # Same, for commands whose non-zero exit is an expected answer rather than an
+        # outage. Warns on stderr — degrading quietly is the bug this class exists to
+        # prevent — and returns nil. A timeout is never an expected answer, so it is left
+        # to propagate and fail the source.
+        #
+        # @param consequence [String] what the report loses, for the operator reading stderr
+        # @return [String, nil] stdout, or nil when git exited non-zero
+        def output_or_nil(args, consequence:)
+          output(args)
+        rescue CommandError => e
+          warn "[git] #{e.message}"
+          warn "  #{consequence}"
+          nil
+        end
+
+        # Runs a git command for its exit status alone, for the questions that have a
+        # non-zero answer rather than a failure ("does this checkout have any commits
+        # yet?"). A timeout still raises — that is not an answer either way.
+        #
+        # @return [Boolean] true when git exited zero
+        def success?(args)
+          _stdout, _stderr, status = run(['git', *args])
+          status.success?
+        end
+
+        private
+
+        # Accepts a number or a numeric string from sources.git.timeout. Anything else —
+        # a typo, a zero, a negative — falls back to the default instead of turning every
+        # git call into an instant kill.
+        def normalize_timeout(value)
+          seconds = Float(value, exception: false)
+          seconds&.positive? ? seconds : DEFAULT_TIMEOUT_SECONDS
+        end
+
+        # Spawns a command in the repo and returns [stdout, stderr, status].
+        #
+        # Open3.capture2 is not used here, and neither would Timeout.timeout around it
+        # help: capture2 closes the pipes and then joins the waiter thread in an ensure
+        # block, so a child that ignores the closed pipe leaves that join hanging with the
+        # timeout exception already in flight — the hang this method exists to end.
+        # Driving popen3 directly is what makes the kill below possible.
+        def run(cmd)
+          # pgroup: the child leads its own process group, so #terminate can signal the
+          # whole tree. git delegates to helpers — a credential helper, an alias running a
+          # shell — and signalling the git process alone would leave those behind, still
+          # holding the pipes this method is waiting on.
+          Open3.popen3(*cmd, chdir: @repo_path, pgroup: true) do |stdin, stdout, stderr, wait_thr|
+            stdin.close
+            # Drained on their own threads: a command that fills the stderr pipe while we
+            # block on stdout deadlocks, and both have to keep draining while we wait.
+            out_reader = Thread.new { stdout.read }
+            err_reader = Thread.new { stderr.read }
+
+            unless wait_thr.join(@timeout_seconds)
+              terminate(wait_thr)
+              abandon(out_reader, err_reader)
+              raise TimeoutError, timeout_message(cmd)
+            end
+
+            # Read after the wait, not before: it is the exiting process closing its end
+            # of the pipes that lets these two threads finish.
+            [out_reader.value, err_reader.value, wait_thr.value]
+          end
+        end
+
+        # Ends the process group of a command that overran the timeout. Errno::ESRCH means
+        # it exited on its own between the join giving up and the signal landing — a race
+        # we win by ignoring, since that exit is what the signal was asking for.
+        def terminate(wait_thr)
+          Process.kill('TERM', -wait_thr.pid)
+          return if wait_thr.join(TERMINATE_GRACE_SECONDS)
+
+          Process.kill('KILL', -wait_thr.pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        # The output is discarded on the timeout path, so the drain threads get a deadline
+        # rather than the unbounded read they are in the middle of: anything that survived
+        # the KILL can still be holding the write end of the pipe open.
+        def abandon(*readers)
+          readers.each { |reader| reader.kill unless reader.join(TERMINATE_GRACE_SECONDS) }
+        end
+
+        def timeout_message(cmd)
+          scrub_credentials("#{describe(cmd)} did not finish within #{@timeout_seconds}s " \
+                            "in #{@repo_path} and was killed")
+        end
+
+        def failure_message(cmd:, status:, stderr:)
+          message = "#{describe(cmd)} failed in #{@repo_path} (#{exit_description(status)})"
+          detail = stderr_summary(stderr)
+          scrub_credentials(detail.empty? ? message : "#{message}: #{detail}")
+        end
+
+        def exit_description(status)
+          return "exit status #{status.exitstatus}" if status.exitstatus
+
+          "terminated by signal #{status.termsig}"
+        end
+
+        # These messages reach a report through Orchestrator#failed_sources. Arguments are
+        # built from refs and format strings rather than typed by hand, so anything
+        # unprintable in one is escaped rather than smuggled into HTML and Markdown output.
+        def describe(cmd)
+          cmd.join(' ').gsub(/[^[:print:]]/) { |char| format('\\x%02X', char.ord) }
+        end
+
+        def stderr_summary(stderr)
+          summary = stderr.to_s.strip.lines.first(MAX_STDERR_LINES)
+                          .map(&:strip).reject(&:empty?).join('; ')
+          return summary unless summary.length > MAX_STDERR_CHARS
+
+          "#{summary[0, MAX_STDERR_CHARS]}…"
+        end
+
+        # A remote URL can carry a token (https://ghp_xxx@github.com/...), and it reaches
+        # these messages from both sides: git echoes the URL in its errors, and a command
+        # can take one as an argument. The messages travel further than the console —
+        # Orchestrator#failed_sources puts them in the report — so they get the same
+        # credential stripping Git#normalize_remote_url applies to the URL itself.
+        def scrub_credentials(message)
+          message.gsub(%r{://[^\s/]*@}, '://')
+        end
+      end
+    end
+  end
+end