ace-llm-providers-cli 0.35.2 → 0.36.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bac39a45138ac76601934b27fe805438a6ce47a48dfe74da044c267ba80c92e
-  data.tar.gz: 6dd39dd18370dff38db534c0e95848b735061ce336652324fa3df7b905bd5432
+  metadata.gz: b9149be64f8f384f5636b393bfa3cf12f81aa9488e486225ed2966c731ef2a0f
+  data.tar.gz: 1fe4000a4a8000d49e04796a2eee4030b588cc3ef06babb2080b2e7feb66dedf
 SHA512:
-  metadata.gz: c1b64b8309c1a2ec15e621d07fc074840325ea8c9893cbe9e109b0775d326f581e3ef4eaeb1b0155aaf6194d29fec5c5a459d0c8cb2adc15854d9c7ec4a2f4cb
-  data.tar.gz: 676c4e56fcee33792c4595fe8291cf2ba9834d3e450a452f93de04fd69733212138a38cec9312b4b2ff5ebbde44f798da69e97a63df829024d12e56f7b9a2381
+  metadata.gz: 7fc14db03c5a90eae90ec8855bb7bd801d5a75c5174488335b1201bd10d767c4f202eb192008b6a932c3c717e4913df2ae2cdd8650a16ebfd1921d3d50b57687
+  data.tar.gz: 1f2b33eb5461854fb293d583eebf87d723c0aa2ecd560995a6b05e56f00da0ba8570fedcd9531c853ccd24b055f64129721961d87988fd599378734c18507eca

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.1] - 2026-10-01
+
+### Technical
+- Observe descendant exit with a bounded monotonic wait in cleanup tests, retaining the process-absence predicate and adding a live-child negative control.
+
+## [0.36.0] - 2026-09-29
+
+### Added
+- `Models::CaptureResult`: typed outcome of one subprocess capture (completed / deadline-exceeded / transport failure / spawn failure) carrying raw streams internally, plus exit status, signal, configured deadline, monotonic elapsed time, and an opaque invocation ID generated before spawn. Evidence leaves only as bounded, redacted excerpts.
+
+### Changed
+- `SafeCapture.call` returns a `CaptureResult` instead of a bare `[stdout, stderr, status]` tuple and no longer raises on deadline expiry; spawn failures (binary not found) become a typed outcome instead of a raw `Errno`. Process-group cleanup, partial-stream retention, and the Linux subreaper supervisor are preserved. Deadline measurement uses the monotonic clock.
+- All CLI provider clients (codex, codexoai, claude, claudeoai, gemini, pi, opencode, agy) consume the typed result and raise `ProviderError`s that carry structured execution evidence; provider-reported auth failures (pi 401) still surface as `AuthenticationError`.
+
 ## [0.35.2] - 2026-09-29
 
 ### Changed

data/lib/ace/llm/providers/cli/agy_client.rb

@@ -57,9 +57,10 @@ module Ace
             )
 
             cmd = build_agy_command(prompt, options)
-            stdout, stderr, status = execute_agy_command(cmd, working_dir: working_dir, options: options)
+            capture = execute_agy_command(cmd, working_dir: working_dir, options: options)
+            capture.raise_unless_success
 
-            parse_agy_response(stdout, stderr, status, prompt)
+            parse_agy_response(capture, prompt)
           rescue => e
             handle_agy_error(e)
           end
@@ -177,17 +178,18 @@ module Ace
             )
           end
 
-          def parse_agy_response(stdout, stderr, status, prompt)
-            response = if stream_json_output?(stdout)
-              parse_stream_json(stdout)
+          def parse_agy_response(capture, prompt)
+            response = if stream_json_output?(capture.stdout)
+              parse_stream_json(capture.stdout)
             else
-              parse_json_or_text(stdout)
+              parse_json_or_text(capture.stdout)
             end
 
             error_message = response["error"].to_s
-            run_status = response.fetch("status", status.success? ? "SUCCESS" : "ERROR")
-            if !status.success? || run_status != "SUCCESS"
-              raise Ace::LLM::ProviderError, build_failure_message(error_message, stderr, stdout, run_status)
+            run_status = response.fetch("status", "SUCCESS")
+            if run_status != "SUCCESS"
+              raise Ace::LLM::ProviderError,
+                build_failure_message(error_message, capture.stderr, capture.stdout, run_status)
             end
 
             text = extract_response_text(response)

data/lib/ace/llm/providers/cli/claude_code_client.rb

@@ -60,15 +60,16 @@ module Ace
               working_dir: options[:working_dir],
               subprocess_env: subprocess_env
             )
-            stdout, stderr, status = execute_claude_command(
+            capture = execute_claude_command(
               cmd,
               prompt,
               subprocess_env: subprocess_env,
               working_dir: working_dir,
               subprocess_command_prefix: options[:subprocess_command_prefix]
             )
+            capture.raise_unless_success
 
-            parse_claude_response(stdout, stderr, status, prompt, options)
+            parse_claude_response(capture, prompt, options)
           rescue => e
             handle_claude_error(e)
           end
@@ -279,18 +280,20 @@ module Ace
             filtered
           end
 
-          def parse_claude_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
-              raise Ace::LLM::ProviderError, "Claude CLI failed: #{error_msg}"
+          def parse_claude_response(capture, prompt, options)
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+              raise capture.provider_error("Claude CLI failed: #{error_msg}")
             end
 
             begin
               # Allow duplicate keys to avoid warnings from Claude CLI output
               # Some versions of Claude CLI may return JSON with duplicate keys
-              response = JSON.parse(stdout, allow_duplicate_key: true)
+              response = JSON.parse(capture.stdout, allow_duplicate_key: true)
             rescue JSON::ParserError => e
-              raise Ace::LLM::ProviderError, "Failed to parse Claude response: #{e.message}"
+              raise capture.with_no_response_evidence(
+                Ace::LLM::ProviderError.new("Failed to parse Claude response: #{e.message}")
+              )
             end
 
             if response["is_error"]
@@ -301,7 +304,9 @@ module Ace
             text = extract_claude_text(response)
 
             if text.strip.empty?
-              raise Ace::LLM::ProviderError, build_response_error(response)
+              raise capture.with_no_response_evidence(
+                Ace::LLM::ProviderError.new(build_response_error(response))
+              )
             end
 
             # Build metadata

data/lib/ace/llm/providers/cli/claude_oai_client.rb

@@ -57,15 +57,16 @@ module Ace
             prompt = rewrite_skill_commands(prompt, working_dir: working_dir)
 
             cmd = build_claude_command(options)
-            stdout, stderr, status = execute_claude_command(
+            capture = execute_claude_command(
               cmd,
               prompt,
               subprocess_env: subprocess_env,
               working_dir: working_dir,
               subprocess_command_prefix: options[:subprocess_command_prefix]
             )
+            capture.raise_unless_success
 
-            parse_claude_response(stdout, stderr, status, prompt, options)
+            parse_claude_response(capture, prompt, options)
           rescue => e
             handle_claude_error(e)
           end
@@ -229,16 +230,18 @@ module Ace
             "sonnet"
           end
 
-          def parse_claude_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
-              raise Ace::LLM::ProviderError, "Claude OAI CLI failed: #{error_msg}"
+          def parse_claude_response(capture, prompt, options)
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+              raise capture.provider_error("Claude OAI CLI failed: #{error_msg}")
             end
 
             begin
-              response = JSON.parse(stdout, allow_duplicate_key: true)
+              response = JSON.parse(capture.stdout, allow_duplicate_key: true)
             rescue JSON::ParserError => e
-              raise Ace::LLM::ProviderError, "Failed to parse Claude OAI response: #{e.message}"
+              raise capture.with_no_response_evidence(
+                Ace::LLM::ProviderError.new("Failed to parse Claude OAI response: #{e.message}")
+              )
             end
 
             text = response["result"] || response["response"] || ""

data/lib/ace/llm/providers/cli/codex_client.rb

@@ -83,8 +83,9 @@ module Ace
               completed = false
               result = nil
               begin
-                stdout, stderr, status = execute_codex_command(cmd, prompt, execution_options)
-                result = parse_codex_response(stdout, stderr, status, prompt, execution_options)
+                capture = execute_codex_command(cmd, prompt, execution_options)
+                capture.raise_unless_success
+                result = parse_codex_response(capture, prompt, execution_options)
                 completed = true
                 result
               ensure
@@ -320,10 +321,10 @@ module Ace
             )
           end
 
-          def parse_codex_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
-              raise Ace::LLM::ProviderError, "Codex CLI failed: #{error_msg}"
+          def parse_codex_response(capture, prompt, options)
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+              raise capture.provider_error("Codex CLI failed: #{error_msg}")
             end
 
             # The native last-message file contains only the final response,
@@ -331,7 +332,11 @@ module Ace
             last_message_path = options[:last_message_file]
             if last_message_path
               text = File.file?(last_message_path) ? File.read(last_message_path).strip : ""
-              raise Ace::LLM::ProviderError, "Codex CLI produced no final message" if text.empty?
+              if text.empty?
+                raise capture.with_no_response_evidence(
+                  Ace::LLM::ProviderError.new("Codex CLI produced no final message")
+                )
+              end
 
               return {text: text, metadata: build_synthetic_metadata(text, prompt)}
             end
@@ -340,7 +345,7 @@ module Ace
             # only when a real CLI banner is present, not when report prose
             # happens to contain a standalone `codex` line.
             # Codex output includes metadata lines and the actual response
-            lines = stdout.split("\n")
+            lines = capture.stdout.split("\n")
 
             has_cli_banner = lines.first(20).any? { |line| line.start_with?("OpenAI Codex v") }
             response_start = lines.find_index { |line| line.strip == "codex" } if has_cli_banner
@@ -353,7 +358,7 @@ module Ace
               text = response_lines.join("\n").strip
             else
               # Fallback: use entire output if we can't parse the format
-              text = stdout.strip
+              text = capture.stdout.strip
             end
 
             # Build metadata

data/lib/ace/llm/providers/cli/codex_oai_client.rb

@@ -58,9 +58,10 @@ module Ace
             prompt = rewrite_skill_commands(prompt, working_dir: working_dir)
 
             cmd = build_codex_oai_command(prompt, options, working_dir: working_dir)
-            stdout, stderr, status = execute_codex_command(cmd, prompt, options)
+            capture = execute_codex_command(cmd, prompt, options)
+            capture.raise_unless_success
 
-            parse_codex_response(stdout, stderr, status, prompt, options)
+            parse_codex_response(capture, prompt, options)
           rescue => e
             handle_codex_error(e)
           end
@@ -203,13 +204,13 @@ module Ace
             )
           end
 
-          def parse_codex_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
-              raise Ace::LLM::ProviderError, "Codex OAI CLI failed: #{error_msg}"
+          def parse_codex_response(capture, prompt, options)
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+              raise capture.provider_error("Codex OAI CLI failed: #{error_msg}")
             end
 
-            lines = stdout.split("\n")
+            lines = capture.stdout.split("\n")
             response_start = lines.find_index { |line| line.include?("codex") }
 
             if response_start && response_start < lines.length - 1
@@ -217,7 +218,7 @@ module Ace
               response_lines = response_lines.reject { |line| line.include?("tokens used") }
               text = response_lines.join("\n").strip
             else
-              text = stdout.strip
+              text = capture.stdout.strip
             end
 
             metadata = build_synthetic_metadata(text, prompt)

data/lib/ace/llm/providers/cli/gemini_client.rb

@@ -56,9 +56,10 @@ module Ace
             prompt = format_messages_as_prompt(messages)
 
             cmd = build_gemini_command(prompt, options)
-            stdout, stderr, status = execute_gemini_command(cmd, prompt, options)
+            capture = execute_gemini_command(cmd, prompt, options)
+            capture.raise_unless_success
 
-            parse_gemini_response(stdout, stderr, status, prompt, options)
+            parse_gemini_response(capture, prompt, options)
           end
 
           # List available Gemini models
@@ -274,15 +275,15 @@ module Ace
             )
           end
 
-          def parse_gemini_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
-              raise Ace::LLM::ProviderError, "Gemini CLI failed: #{error_msg}"
+          def parse_gemini_response(capture, prompt, options)
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+              raise capture.provider_error("Gemini CLI failed: #{error_msg}")
             end
 
             # Try to parse JSON output first
             begin
-              parsed = JSON.parse(stdout)
+              parsed = JSON.parse(capture.stdout)
 
               # Extract response text from parsed JSON
               # Gemini CLI JSON format: { "response": "...", "stats": { ... } }
@@ -292,14 +293,14 @@ module Ace
                 parsed["candidates"].first["content"] || parsed["candidates"].first["text"]
               else
                 # Fallback to raw output if JSON structure unexpected
-                stdout.strip
+                capture.stdout.strip
               end
 
               # Extract metadata from stats if available
               metadata = extract_metadata_from_json(parsed, prompt)
             rescue JSON::ParserError
               # Fallback to raw text output if JSON parsing fails
-              text = stdout.strip
+              text = capture.stdout.strip
               metadata = build_synthetic_metadata(text, prompt)
             end
 

data/lib/ace/llm/providers/cli/models/capture_result.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require "ace/llm/models/execution_evidence"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Models
+          # Typed outcome of one SafeCapture subprocess invocation.
+          #
+          # Carries the raw captured streams and the process facts (outcome kind,
+          # exit/signal, configured deadline, monotonic elapsed time, invocation
+          # correlation ID) so classification downstream can key on evidence
+          # instead of error-message prose. Raw streams stay internal to this
+          # object; only bounded excerpts leave through #execution_evidence.
+          #
+          # This is a model - pure immutable data.
+          class CaptureResult
+            OUTCOME_COMPLETED = :completed
+            OUTCOME_DEADLINE_EXCEEDED = :deadline_exceeded
+            OUTCOME_TRANSPORT_FAILURE = :transport_failure
+            OUTCOME_SPAWN_FAILURE = :spawn_failure
+
+            MAX_MESSAGE_LENGTH = 2000
+
+            # Generate the correlation ID for an invocation before spawning.
+            # @return [String] opaque 8-character ID
+            def self.next_invocation_id
+              SecureRandom.alphanumeric(8)
+            end
+
+            # @param outcome [Symbol] one of the OUTCOME_* constants
+            # @param stdout [String] captured stdout (empty when nothing captured)
+            # @param stderr [String] captured stderr (empty when nothing captured)
+            # @param status [Process::Status, nil] exit status (nil when the process never exited on its own)
+            # @param signal [String, nil] terminating signal name (derived from status when not given)
+            # @param provider_name [String] human-facing provider label
+            # @param invocation_id [String] correlation ID generated before spawn
+            # @param deadline_seconds [Numeric, nil] configured deadline
+            # @param elapsed_seconds [Numeric, nil] monotonic elapsed time
+            # @param spawn_error [Exception, nil] exception that prevented spawning
+            def initialize(outcome:, stdout: "", stderr: "", status: nil, signal: nil, provider_name: "CLI",
+              invocation_id: Models::CaptureResult.next_invocation_id, deadline_seconds: nil,
+              elapsed_seconds: nil, spawn_error: nil)
+              @outcome = outcome
+              @stdout = stdout.to_s
+              @stderr = stderr.to_s
+              @status = status
+              @signal = signal
+              @provider_name = provider_name
+              @invocation_id = invocation_id
+              @deadline_seconds = deadline_seconds
+              @elapsed_seconds = elapsed_seconds
+              @spawn_error = spawn_error
+              freeze
+            end
+
+            attr_reader :outcome, :stdout, :stderr, :status, :signal, :provider_name,
+              :invocation_id, :deadline_seconds, :elapsed_seconds, :spawn_error
+
+            # True when the process ran to its own completion and exited zero.
+            def success?
+              outcome == OUTCOME_COMPLETED && status&.success? ? true : false
+            end
+
+            # True when the provider process was actually spawned. Failed spawns
+            # never began execution, so replaying them cannot repeat side effects.
+            def execution_began?
+              outcome != OUTCOME_SPAWN_FAILURE
+            end
+
+            def exit_status
+              status&.exitstatus
+            end
+
+            def signal
+              return @signal if @signal
+              return nil if outcome == OUTCOME_SPAWN_FAILURE
+
+              termsig = status&.termsig
+              termsig ? (Signal.list.key(termsig) || "signal #{termsig}") : nil
+            end
+
+            # Structured evidence for classification, with bounded output excerpts.
+            # @return [Ace::LLM::Models::ExecutionEvidence]
+            def execution_evidence
+              Ace::LLM::Models::ExecutionEvidence.new(
+                outcome: evidence_outcome,
+                invocation_id: invocation_id,
+                provider_name: provider_name,
+                deadline_seconds: deadline_seconds,
+                elapsed_seconds: elapsed_seconds,
+                exit_status: exit_status,
+                signal: signal,
+                execution_began: execution_began?,
+                stdout_excerpt: stdout,
+                stderr_excerpt: stderr
+              )
+            end
+
+            # Build the ProviderError describing this outcome, with evidence attached.
+            # Explicit caller messages can embed raw CLI output, so they are
+            # redacted and bounded here — never trusted as-is.
+            # @return [Ace::LLM::ProviderError]
+            def provider_error(message = nil)
+              text = Ace::LLM::Models::ExecutionEvidence.redact(message || default_error_message)
+              text = "#{text[0, MAX_MESSAGE_LENGTH]}…[truncated]" if text.length > MAX_MESSAGE_LENGTH
+              error = Ace::LLM::ProviderError.new(text)
+              error.execution_evidence = execution_evidence
+              error
+            end
+
+            # Raise ProviderError unless the invocation completed with exit 0.
+            # Deadline expiry, transport failure, spawn failure, and nonzero exit
+            # each surface as a distinct, evidence-carrying error.
+            def raise_unless_success
+              raise provider_error unless success?
+
+              self
+            end
+
+            # Attach "session ended without a final response" evidence to an error
+            # raised while parsing a completed (exit-zero) capture — e.g. a CLI
+            # that exited cleanly but produced no final message. The message is
+            # redacted before being carried forward.
+            # @param error [Ace::LLM::ProviderError]
+            # @return [Ace::LLM::ProviderError]
+            def with_no_response_evidence(error)
+              message = Ace::LLM::Models::ExecutionEvidence.redact(error.message.to_s)
+              message = "#{message[0, MAX_MESSAGE_LENGTH]}…[truncated]" if message.length > MAX_MESSAGE_LENGTH
+              redacted = error.exception(message)
+              evidence = Ace::LLM::Models::ExecutionEvidence.new(
+                outcome: :no_response,
+                invocation_id: invocation_id,
+                provider_name: provider_name,
+                deadline_seconds: deadline_seconds,
+                elapsed_seconds: elapsed_seconds,
+                exit_status: exit_status,
+                execution_began: true,
+                stdout_excerpt: stdout,
+                stderr_excerpt: stderr
+              )
+              redacted.execution_evidence ||= evidence
+              redacted
+            end
+
+            private
+
+            def evidence_outcome
+              case outcome
+              when OUTCOME_COMPLETED then :nonzero_exit
+              when OUTCOME_DEADLINE_EXCEEDED then :deadline_exceeded
+              when OUTCOME_TRANSPORT_FAILURE, OUTCOME_SPAWN_FAILURE then :transport_failure
+              end
+            end
+
+            def default_error_message
+              case outcome
+              when OUTCOME_DEADLINE_EXCEEDED
+                "#{provider_name} CLI execution exceeded its #{format_seconds(deadline_seconds)} deadline"
+              when OUTCOME_TRANSPORT_FAILURE
+                "#{provider_name} CLI session ended unexpectedly" + (signal ? " (#{signal})" : "")
+              when OUTCOME_SPAWN_FAILURE
+                "#{provider_name} CLI could not be started: #{spawn_error_class}"
+              else
+                base = "#{provider_name} CLI failed with exit status #{exit_status}"
+                (detail = failure_detail) ? "#{base}: #{detail}" : base
+              end
+            end
+
+            # First non-empty captured line, bounded and redacted — keeps
+            # actionable CLI diagnostics in the error without leaking
+            # transcripts or credentials.
+            def failure_detail
+              source = [stderr, stdout].map { |stream| stream.to_s.lines.map(&:strip) }.flatten
+              detail = source.reject(&:empty?).first.to_s
+              detail = Ace::LLM::Models::ExecutionEvidence.redact(detail)
+              detail = "#{detail[0, 300]}…[truncated]" if detail.length > 300
+              detail.empty? ? nil : detail
+            end
+
+            def spawn_error_class
+              spawn_error ? spawn_error.class.name : "unknown error"
+            end
+
+            def format_seconds(value)
+              value.is_a?(Numeric) ? format("%.1fs", value) : value.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/molecules/process_supervisor.rb

@@ -17,7 +17,15 @@ module Ace
             def run(command)
               enable_child_subreaper
               ready_fd = Integer(ENV.delete("ACE_SAFE_CAPTURE_READY_FD"))
-              command_pid = Process.spawn(*command, pgroup: true, ready_fd => :close)
+              command_pid = begin
+                Process.spawn(*command, pgroup: true, ready_fd => :close)
+              rescue StandardError => e
+                # The child never started: tell the capture through the
+                # readiness pipe so it records a spawn failure, not an
+                # executed (nonzero-exit) child session.
+                report_spawn_failure(ready_fd, e)
+                raise
+              end
               command_pgid = command_pid
               IO.for_fd(ready_fd).tap { |io| io.write("1"); io.close }
 
@@ -30,6 +38,15 @@ module Ace
               exit(status.exitstatus || 128 + status.termsig)
             end
 
+            def report_spawn_failure(ready_fd, error)
+              IO.for_fd(ready_fd).tap do |io|
+                io.write("S#{error.class.name}: #{error.message}")
+                io.close
+              end
+            rescue SystemCallError, IOError
+              nil
+            end
+
             def enable_child_subreaper
               previous_deprecated = Warning[:deprecated]
               Warning[:deprecated] = false

data/lib/ace/llm/providers/cli/molecules/safe_capture.rb

@@ -3,6 +3,8 @@
 require "open3"
 require "rbconfig"
 
+require_relative "../models/capture_result"
+
 module Ace
   module LLM
     module Providers
@@ -17,6 +19,10 @@ module Ace
           # Uses Open3.popen3 and, on Linux, a dedicated child-subreaper supervisor
           # so the complete command tree is terminated and reaped without thread
           # interruption or closed-stream races.
+          #
+          # Returns a typed Models::CaptureResult instead of a bare tuple so
+          # callers can distinguish completed runs from deadline expiry, transport
+          # failure, and spawn failure, and carry that evidence into errors.
           class SafeCapture
             # @param cmd [Array<String>] Command arguments
             # @param timeout [Integer] Timeout in seconds
@@ -26,85 +32,246 @@ module Ace
             # @param provider_name [String] Provider name for error messages
             # @param isolate_process_group [Boolean] Spawn subprocess in isolated process group
             # @param cleanup_group_on_exit [Boolean] Clean up descendants on success
-            # @return [Array(String, String, Process::Status)] [stdout, stderr, status]
-            # @raise [Ace::LLM::ProviderError] on timeout
+            # @return [Models::CaptureResult] typed capture outcome with raw streams
             def self.call(cmd, timeout:, stdin_data: nil, chdir: nil, env: nil, provider_name: "CLI",
               command_prefix: nil,
               isolate_process_group: true, cleanup_group_on_exit: true)
               normalized_timeout = normalize_timeout(timeout)
-              opts = {}
-              opts[:chdir] = chdir if chdir
-              opts[:pgroup] = true if isolate_process_group
-
-              full_cmd = Array(command_prefix) + cmd
-              supervised = isolate_process_group && cleanup_group_on_exit && RUBY_PLATFORM.include?("linux")
-              full_cmd = supervisor_command(full_cmd) if supervised
-              ready_reader, ready_writer = IO.pipe if supervised
-              opts[ready_writer.fileno] = ready_writer if supervised
-              spawn_env = env&.dup || {}
-              spawn_env["ACE_SAFE_CAPTURE_READY_FD"] = ready_writer.fileno.to_s if supervised
-              args = spawn_env.empty? ? full_cmd : [spawn_env, *full_cmd]
-
-              Open3.popen3(*args, **opts) do |stdin, stdout, stderr, wait_thr|
-                ready_writer&.close
-                ready_reader&.read(1)
-                ready_reader&.close
-
-                pid = wait_thr.pid
-                pgid = safe_getpgid(pid)
-                debug_log(provider_name, "spawn pid=#{pid} pgid=#{pgid || "n/a"}")
-
-                begin
-                  stdin.write(stdin_data) if stdin_data
-                rescue Errno::EPIPE
-                  # Subprocess exited before consuming stdin — continue to capture stderr for the real error
+              invocation_id = Models::CaptureResult.next_invocation_id
+              started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+              spawn_result = begin
+                spawn_subprocess(
+                  cmd, chdir: chdir, env: env, command_prefix: command_prefix,
+                  isolate_process_group: isolate_process_group,
+                  cleanup_group_on_exit: cleanup_group_on_exit
+                )
+              rescue SystemCallError => e
+                return spawn_failure_result(
+                  e, provider_name: provider_name, invocation_id: invocation_id,
+                  deadline_seconds: normalized_timeout, started_at: started_at
+                )
+              end
+
+              begin
+                run_capture(
+                  spawn_result,
+                  provider_name: provider_name,
+                  stdin_data: stdin_data,
+                  isolate_process_group: isolate_process_group,
+                  cleanup_group_on_exit: cleanup_group_on_exit,
+                  normalized_timeout: normalized_timeout,
+                  invocation_id: invocation_id,
+                  started_at: started_at
+                )
+              rescue SystemCallError => e
+                # popen3 raises before the capture block runs when the command
+                # cannot be spawned (e.g. binary not found).
+                spawn_failure_result(
+                  e, provider_name: provider_name, invocation_id: invocation_id,
+                  deadline_seconds: normalized_timeout, started_at: started_at
+                )
+              ensure
+                spawn_result.close_setup_handles
+              end
+            end
+
+            class << self
+              private
+
+              SpawnSetup = Struct.new(:args, :opts, :supervised, :ready_reader, :ready_writer, :readiness,
+                keyword_init: true) do
+                def supervised?
+                  supervised
                 end
-                stdin.close
 
-                out_reader = Thread.new { safe_read_stream(stdout) }
-                err_reader = Thread.new { safe_read_stream(stderr) }
-                out_reader.report_on_exception = false
-                err_reader.report_on_exception = false
+                # Read the supervisor's readiness message (small, bounded; the
+                # supervisor closes the pipe after writing). "1" means the child
+                # group spawned; "S<detail>" reports a child spawn failure.
+                def activate_streams
+                  ready_writer&.close
+                  self.readiness = ready_reader&.read
+                  ready_reader&.close
+                end
 
-                unless wait_thr.join(normalized_timeout)
-                  # Timeout: kill subprocess group (and descendants), then clean up
-                  terminate_subprocess_tree(
-                    pid: pid, pgid: pgid, provider_name: provider_name, supervised: supervised
-                  )
-                  unless wait_thr.join(5)
-                    terminate_group_or_pid("KILL", pid, pgid)
-                    wait_thr.join(5)
-                  end
+                # StandardError describing a supervisor-reported child spawn
+                # failure, or nil when the child group started normally.
+                def child_spawn_failure
+                  return nil if supervised != true || readiness.nil.
+
+                  message = readiness.to_s
+                  return nil unless message.start_with?("S")
 
-                  stdout.close unless stdout.closed?
-                  stderr.close unless stderr.closed?
-                  out_reader.join(1)
-                  err_reader.join(1)
-                  out_reader.kill if out_reader.alive?
-                  err_reader.kill if err_reader.alive?
-                  raise Ace::LLM::ProviderError,
-                    "#{provider_name} CLI execution timed out after #{normalized_timeout} seconds"
+                  StandardError.new("child process failed to start: #{message[1..].strip}")
                 end
 
-                status = wait_thr.value
-                if isolate_process_group && cleanup_group_on_exit && !supervised
-                  terminate_descendants_after_success(pid: pid, pgid: pgid, provider_name: provider_name)
+                def close_setup_handles
+                  [ready_reader, ready_writer].each do |io|
+                    next unless io
+
+                    io.close unless io.closed?
+                  end
                 end
+              end
+              private_constant :SpawnSetup
 
-                [out_reader.value, err_reader.value, status]
+              def spawn_failure_result(error, provider_name:, invocation_id:, deadline_seconds:, started_at:)
+                Models::CaptureResult.new(
+                  outcome: Models::CaptureResult::OUTCOME_SPAWN_FAILURE,
+                  provider_name: provider_name,
+                  invocation_id: invocation_id,
+                  deadline_seconds: deadline_seconds,
+                  elapsed_seconds: elapsed_since(started_at),
+                  spawn_error: error
+                )
               end
-            ensure
-              ready_reader&.close unless ready_reader&.closed?
-              ready_writer&.close unless ready_writer&.closed?
-            end
 
-            class << self
-              private
+              def run_capture(spawn_result, provider_name:, stdin_data:, isolate_process_group:,
+                cleanup_group_on_exit:, normalized_timeout:, invocation_id:, started_at:)
+                Open3.popen3(*spawn_result.args, **spawn_result.opts) do |stdin, stdout, stderr, wait_thr|
+                  spawn_result.activate_streams
+                  if (spawn_failure = spawn_result.child_spawn_failure)
+                    return Models::CaptureResult.new(
+                      outcome: Models::CaptureResult::OUTCOME_SPAWN_FAILURE,
+                      provider_name: provider_name,
+                      invocation_id: invocation_id,
+                      deadline_seconds: normalized_timeout,
+                      elapsed_seconds: elapsed_since(started_at),
+                      spawn_error: spawn_failure
+                    )
+                  end
+
+                  pid = wait_thr.pid
+                  pgid = safe_getpgid(pid)
+                  debug_log(provider_name, "spawn pid=#{pid} pgid=#{pgid || "n/a"} invocation=#{invocation_id}")
+
+                  begin
+                    stdin.write(stdin_data) if stdin_data
+                  rescue Errno::EPIPE
+                    # Subprocess exited before consuming stdin — continue to capture stderr for the real error
+                  end
+                  stdin.close
 
-              def safe_read_stream(io)
-                io.read
-              rescue IOError
-                ""
+                  partial_stdout = +""
+                  partial_stderr = +""
+                  out_reader = Thread.new { safe_read_stream(stdout, partial_stdout) }
+                  err_reader = Thread.new { safe_read_stream(stderr, partial_stderr) }
+                  out_reader.report_on_exception = false
+                  err_reader.report_on_exception = false
+
+                  unless wait_thr.join(normalized_timeout)
+                    # Deadline exceeded: kill subprocess group (and descendants), retain partial streams
+                    terminate_subprocess_tree(
+                      pid: pid, pgid: pgid, provider_name: provider_name, supervised: spawn_result.supervised?
+                    )
+                    unless wait_thr.join(5)
+                      terminate_group_or_pid("KILL", pid, pgid)
+                      wait_thr.join(5)
+                    end
+
+                    return Models::CaptureResult.new(
+                      outcome: Models::CaptureResult::OUTCOME_DEADLINE_EXCEEDED,
+                      stdout: drain_reader(out_reader, stdout, partial_stdout),
+                      stderr: drain_reader(err_reader, stderr, partial_stderr),
+                      provider_name: provider_name,
+                      invocation_id: invocation_id,
+                      deadline_seconds: normalized_timeout,
+                      elapsed_seconds: elapsed_since(started_at)
+                    )
+                  end
+
+                  status = wait_thr.value
+                  if isolate_process_group && cleanup_group_on_exit && !spawn_result.supervised?
+                    terminate_descendants_after_success(pid: pid, pgid: pgid, provider_name: provider_name)
+                  end
+
+                  outcome = if status.exited?
+                    Models::CaptureResult::OUTCOME_COMPLETED
+                  else
+                    # Terminated by a signal we did not send: the session ended
+                    # abruptly rather than the CLI finishing on its own.
+                    Models::CaptureResult::OUTCOME_TRANSPORT_FAILURE
+                  end
+
+                  return Models::CaptureResult.new(
+                    outcome: outcome,
+                    stdout: out_reader.value.to_s,
+                    stderr: err_reader.value.to_s,
+                    status: status,
+                    provider_name: provider_name,
+                    invocation_id: invocation_id,
+                    deadline_seconds: normalized_timeout,
+                    elapsed_seconds: elapsed_since(started_at)
+                  )
+                end
+              end
+
+              def spawn_subprocess(cmd, chdir:, env:, command_prefix:, isolate_process_group:,
+                cleanup_group_on_exit:)
+                opts = {}
+                opts[:chdir] = chdir if chdir
+                opts[:pgroup] = true if isolate_process_group
+
+                full_cmd = Array(command_prefix) + cmd
+                supervised = isolate_process_group && cleanup_group_on_exit && RUBY_PLATFORM.include?("linux")
+                full_cmd = supervisor_command(full_cmd) if supervised
+                ready_reader, ready_writer = IO.pipe if supervised
+                opts[ready_writer.fileno] = ready_writer if supervised
+                spawn_env = env&.dup || {}
+                spawn_env["ACE_SAFE_CAPTURE_READY_FD"] = ready_writer.fileno.to_s if supervised
+                args = spawn_env.empty? ? full_cmd : [spawn_env, *full_cmd]
+
+                SpawnSetup.new(
+                  args: args,
+                  opts: opts,
+                  supervised: supervised,
+                  ready_reader: ready_reader,
+                  ready_writer: ready_writer,
+                  readiness: nil
+                )
+              end
+
+              # Pull whatever partial output a reader thread captured without
+              # ever blocking past a short bound: a descendant outside the
+              # killed process group can keep the pipe open indefinitely. The
+              # buffer is caller-owned, so bytes already read survive even when
+              # the stream must be closed or the reader thread must be killed.
+              def drain_reader(reader, io, buffer)
+                if reader.join(2)
+                  reader.value.to_s
+                else
+                  io.close unless io.closed?
+                  reader.join(1)
+                  reader.kill if reader.alive?
+                  # The reader may have been killed mid-chunk; finalize the
+                  # partial buffer with the same UTF-8 scrubbing contract.
+                  buffer.dup.force_encoding(Encoding::UTF_8).scrub!
+                end
+              end
+
+              # Incrementally buffer stream output into a caller-owned buffer so
+              # already-read bytes survive even when the stream must be closed
+              # mid-read or the reader thread must be killed.
+              def safe_read_stream(io, buffer)
+                loop do
+                  chunk = io.read_nonblock(65_536, exception: false)
+                  if chunk.nil?
+                    break # EOF
+                  elsif chunk == :wait_readable
+                    IO.select([io])
+                    next
+                  end
+                  buffer << chunk
+                end
+                # Pipes yield raw bytes; CLI output can contain non-UTF-8
+                # fragments. Finalize as valid UTF-8 (invalid bytes become
+                # replacement characters) so downstream prompt concatenation
+                # cannot raise Encoding::CompatibilityError.
+                buffer.force_encoding(Encoding::UTF_8)
+                buffer.scrub!
+                buffer
+              rescue IOError, SystemCallError
+                buffer
               end
 
               def normalize_timeout(value)
@@ -119,6 +286,10 @@ module Ace
                 raise ArgumentError, "timeout must be a positive numeric value, got #{value.inspect}"
               end
 
+              def elapsed_since(started_at)
+                Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+              end
+
               def supervisor_command(command)
                 supervisor = File.expand_path("process_supervisor.rb", __dir__)
                 [RbConfig.ruby, "-W0", supervisor, *command]

data/lib/ace/llm/providers/cli/open_code_client.rb

@@ -54,9 +54,10 @@ module Ace
             full_prompt = build_full_prompt(prompt, options)
 
             cmd = build_opencode_command_with_prompt(full_prompt, options)
-            stdout, stderr, status = execute_opencode_command(cmd, options: options)
+            capture = execute_opencode_command(cmd, options: options)
+            capture.raise_unless_success
 
-            parse_opencode_response(stdout, stderr, status, full_prompt, options)
+            parse_opencode_response(capture, full_prompt, options)
           rescue => e
             handle_opencode_error(e)
           end
@@ -211,25 +212,27 @@ module Ace
             )
           end
 
-          def parse_opencode_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
+          def parse_opencode_response(capture, prompt, options)
+            # Unreachable through generate (raise_unless_success precedes parse),
+            # kept for direct callers with clearer 400 diagnostics.
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
 
               # Detect common error patterns for better error messages
               if error_msg.include?("400") || error_msg.include?("Bad Request")
                 raise Ace::LLM::ProviderError, "OpenCode API request failed (400 Bad Request). The model or prompt may be invalid."
               end
 
-              raise Ace::LLM::ProviderError, "OpenCode CLI failed: #{error_msg}"
+              raise capture.provider_error("OpenCode CLI failed: #{error_msg}")
             end
 
             begin
               # Try to parse as JSON first
-              response = JSON.parse(stdout)
+              response = JSON.parse(capture.stdout)
               text = response["result"] || response["text"] || response["response"] || ""
             rescue JSON::ParserError
               # Fall back to treating entire output as text
-              text = stdout.strip
+              text = capture.stdout.strip
               response = {}
             end
 

data/lib/ace/llm/providers/cli/pi_client.rb

@@ -57,9 +57,20 @@ module Ace
             full_prompt = rewrite_skill_commands(full_prompt, working_dir: working_dir)
 
             cmd = build_pi_command(full_prompt, options, system_prompt: system_prompt)
-            stdout, stderr, status = execute_pi_command(cmd, working_dir: working_dir, options: options)
+            capture = execute_pi_command(cmd, working_dir: working_dir, options: options)
+            begin
+              capture.raise_unless_success
+            rescue Ace::LLM::ProviderError
+              raise if !capture.status || capture.status.success?
 
-            parse_pi_response(stdout, stderr, status, full_prompt, options)
+              # 401 output means credentials, not a generic CLI failure —
+              # AuthenticationError classifies as skip-to-next-provider.
+              raise auth_error if captured_auth_failure?(capture)
+
+              raise
+            end
+
+            parse_pi_response(capture, full_prompt, options)
           rescue => e
             handle_pi_error(e)
           end
@@ -275,18 +286,38 @@ module Ace
             )
           end
 
-          def parse_pi_response(stdout, stderr, status, prompt, options)
-            unless status.success?
-              error_msg = stderr.empty? ? stdout : stderr
+          # 401/Unauthorized anywhere in captured output marks a credentials
+          # failure rather than a generic CLI error.
+          def captured_auth_failure?(capture)
+            output = "#{capture.stderr}\n#{capture.stdout}"
+            output.include?("401") || output.include?("Unauthorized")
+          end
 
-              if error_msg.include?("401") || error_msg.include?("Unauthorized")
+          def auth_error
+            Ace::LLM::AuthenticationError.new("Pi authentication failed. Run 'pi login' to configure credentials.")
+          end
+
+          def parse_pi_response(capture, prompt, options)
+            # Unreachable through generate (raise_unless_success precedes parse),
+            # kept for direct callers: auth failures stay AuthenticationError.
+            unless capture.status.success?
+              error_msg = capture.stderr.empty? ? capture.stdout : capture.stderr
+
+              if captured_auth_failure?(capture)
                 raise Ace::LLM::AuthenticationError, "Pi authentication failed. Run 'pi login' to configure credentials."
               end
 
-              raise Ace::LLM::ProviderError, "Pi CLI failed: #{error_msg}"
+              raise capture.provider_error("Pi CLI failed: #{error_msg}")
             end
 
-            text, usage, finish_reason = parse_ndjson(stdout)
+            text, usage, finish_reason = parse_ndjson(capture.stdout)
+            if text.to_s.strip.empty?
+              # Clean exit without a final response: an incomplete session,
+              # not a completed answer.
+              raise capture.with_no_response_evidence(
+                Ace::LLM::ProviderError.new("Pi CLI produced no final message")
+              )
+            end
             response = {"usage" => normalize_usage(usage), "finish_reason" => finish_reason}
 
             metadata = build_metadata(response, text, prompt, options)

data/lib/ace/llm/providers/cli/version.rb

@@ -4,7 +4,7 @@ module Ace
   module LLM
     module Providers
       module CLI
-        VERSION = "0.35.2"
+        VERSION = "0.36.1"
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-llm-providers-cli
 version: !ruby/object:Gem::Version
-  version: 0.35.2
+  version: 0.36.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-llm
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.41'
+        version: '0.42'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.41'
+        version: '0.42'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -110,6 +110,7 @@ files:
 - lib/ace/llm/providers/cli/codex_client.rb
 - lib/ace/llm/providers/cli/codex_oai_client.rb
 - lib/ace/llm/providers/cli/gemini_client.rb
+- lib/ace/llm/providers/cli/models/capture_result.rb
 - lib/ace/llm/providers/cli/molecules/health_checker.rb
 - lib/ace/llm/providers/cli/molecules/process_supervisor.rb
 - lib/ace/llm/providers/cli/molecules/safe_capture.rb