claude-agent-sdk 0.33.0 → 0.34.0

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -19,6 +19,11 @@ module ClaudeAgentSDK
     CLI_PATH_ENV_VAR = 'CLAUDE_CLI_PATH'
     VERSION_CHECK_TIMEOUT_SECONDS = 2 # mirrors Python's anyio.fail_after(2)
     RECENT_STDERR_LINES_LIMIT = 20
+    # After stdout EOF the child has closed (or lost) its last stdout handle,
+    # so it is normally already exiting; a CLI still running this long
+    # afterwards is wedged and gets the same TERM -> KILL ladder as #close.
+    EOF_EXIT_GRACE_SECONDS = 5
+    EOF_TERM_GRACE_SECONDS = 2
 
     # Track live CLI subprocesses so we can terminate them when the parent Ruby
     # process exits. Mirrors the Python (PR #916, a `set[Process]`) and
@@ -110,6 +115,17 @@ module ClaudeAgentSDK
       # close can nil @stdin between write's readiness check and the actual
       # @stdin.write call, producing NoMethodError on nil.
       @stdin_mutex = Mutex.new
+      # Writers holding a live @stdin snapshot (inside #write's IO call),
+      # keyed by Fiber.current, valued by that fiber's Fiber.scheduler (nil
+      # for a plain thread). Inserted in #write's snapshot critical section,
+      # so once stdin is detached under @stdin_mutex the registry holds
+      # exactly the writers that can still touch the IO; deletes and reads
+      # are single GVL-atomic Hash calls and take no lock (a lock in #write's
+      # ensure could suspend a writer mid-unwind). Consulted when stdin is
+      # closed: closing the fd neither wakes a fiber parked in IO#write nor
+      # lets a reactor-side IO#close return while a plain thread is parked
+      # there — see #wake_parked_fiber_writers / #close_stdin_io.
+      @inflight_writers = {}
     end
 
     # Probe order (first hit wins):
@@ -152,18 +168,25 @@ module ClaudeAgentSDK
       end
       return cli if cli && !cli.empty? && File.executable?(cli)
 
-      # Try common locations
+      # Try common locations. The home-relative ones are skipped when no
+      # usable home exists (see #home_dir), so a HOME-less container still
+      # reaches the actionable CLINotFoundError below.
+      home = home_dir
+      under_home = ->(rel) { File.join(home, rel) if home }
       locations = [
-        File.join(Dir.home, '.claude/local/claude'),  # Claude Code default install location
-        File.join(Dir.home, '.npm-global/bin/claude'),
+        under_home.call('.claude/local/claude'), # Claude Code default install location
+        under_home.call('.npm-global/bin/claude'),
         '/usr/local/bin/claude',
-        File.join(Dir.home, '.local/bin/claude'),
-        File.join(Dir.home, 'node_modules/.bin/claude'),
-        File.join(Dir.home, '.yarn/bin/claude')
-      ]
+        under_home.call('.local/bin/claude'),
+        under_home.call('node_modules/.bin/claude'),
+        under_home.call('.yarn/bin/claude')
+      ].compact
 
       locations.each do |path|
-        return path if File.exist?(path) && File.file?(path)
+        # Same test as the CLAUDE_CLI_PATH branch: a non-executable file here
+        # would otherwise be accepted and fail at spawn with a raw EACCES
+        # instead of CLINotFoundError's install instructions.
+        return path if File.file?(path) && File.executable?(path)
       end
 
       raise CLINotFoundError.new(
@@ -174,7 +197,7 @@ module ClaudeAgentSDK
         "\n\nOr provide the path via ClaudeAgentOptions:\n" \
         "  ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
         "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n" \
-        "  ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')" \
+        "  ClaudeAgentSDK::CLIInstaller.install_pinned  # installs #{CLIInstaller::PINNED_CLI_VERSION}" \
         "\n\nOr point the SDK at an existing binary:\n" \
         "  export #{CLI_PATH_ENV_VAR}=/path/to/claude"
       )
@@ -314,6 +337,11 @@ module ClaudeAgentSDK
       return unless @stderr
 
       @stderr.each_line("\n", @max_buffer_size + 1) do |line|
+        # Scrubbed at read time like stdout frames and the version probe: the
+        # CLI (or a tool it runs) can emit invalid UTF-8 on stderr, and an
+        # invalid string handed to the callback or kept for ProcessError#stderr
+        # raises later in the user's encoding work (JSON logging/exporters).
+        line = line.scrub unless line.valid_encoding?
         line_str = line.chomp
         next if line_str.empty?
 
@@ -352,6 +380,7 @@ module ClaudeAgentSDK
       return unless @stderr
 
       @stderr.each_line("\n", @max_buffer_size + 1) do |line|
+        line = line.scrub unless line.valid_encoding? # see #handle_stderr
         line_str = line.chomp
         next if line_str.empty?
 
@@ -375,8 +404,8 @@ module ClaudeAgentSDK
         # interpreter exit (the at_exit reaper fires only then, TERM only).
         # Nothing here may suspend: a synchronous TERM plus a plain
         # background thread for the KILL escalation. On this path the
-        # process deliberately STAYS in the at_exit registry as a second
-        # safety net; the normal path deregisters in teardown_process.
+        # process stays in the at_exit registry until the fallback confirms
+        # it was reaped; the normal path deregisters in teardown_process.
         force_terminate_in_background(process) unless process_teardown_complete
 
         # Snapshot-then-nil BEFORE the best-effort pipe close below: once the
@@ -407,9 +436,24 @@ module ClaudeAgentSDK
           # Cancellation can land before teardown_process reached the pipe
           # closes. stdout/stderr are read ends (close never blocks); stdin's
           # implicit flush is a no-op in practice because #write flushes
-          # after every write. Best-effort: an IO that is already closed or
-          # fails to close is left to GC, which the nil-ing above enables.
-          [stdin_io, stdout_io, stderr_io].each do |io|
+          # after every write. A fiber writer still parked on it is woken
+          # first — a scheduler hand-off (like close_now's child-task stops)
+          # that resumes this fiber one reactor tick later; a second
+          # cancellation landing there only skips the closes below, which
+          # GC then finishes (termination already ran above). A plain
+          # thread parked there makes close_stdin_io use a detached thread
+          # (wait: false), so the close itself never blocks. Best-effort:
+          # an IO that is already closed or fails to close is left to GC,
+          # which the nil-ing above enables.
+          if stdin_io
+            begin
+              wake_parked_fiber_writers
+              close_stdin_io(stdin_io, wait: false)
+            rescue StandardError
+              nil
+            end
+          end
+          [stdout_io, stderr_io].each do |io|
             io&.close
           rescue StandardError
             nil
@@ -431,22 +475,18 @@ module ClaudeAgentSDK
           @stderr_task.kill
           @stderr_task.join(1)
         rescue StandardError => e
+          raise if e.is_a?(Async::TimeoutError)
+
           cleanup_errors << "stderr thread: #{e.message}"
         end
       end
 
-      # Close stdin under the same lock that guards write — otherwise a
-      # concurrent writer (callbacks running on FiberBoundary threads) can
-      # see @stdin nilled mid-write and hit NoMethodError on nil.
-      @stdin_mutex.synchronize do
-        begin
-          @stdin&.close
-        rescue IOError
-          # Already closed, ignore
-        rescue StandardError => e
-          cleanup_errors << "stdin: #{e.message}"
-        end
-        @stdin = nil
+      begin
+        shutdown_stdin
+      rescue StandardError => e
+        raise if e.is_a?(Async::TimeoutError)
+
+        cleanup_errors << "stdin: #{e.message}"
       end
 
       begin
@@ -454,6 +494,8 @@ module ClaudeAgentSDK
       rescue IOError
         # Already closed, ignore
       rescue StandardError => e
+        raise if e.is_a?(Async::TimeoutError)
+
         cleanup_errors << "stdout: #{e.message}"
       end
 
@@ -462,6 +504,8 @@ module ClaudeAgentSDK
       rescue IOError
         # Already closed, ignore
       rescue StandardError => e
+        raise if e.is_a?(Async::TimeoutError)
+
         cleanup_errors << "stderr: #{e.message}"
       end
 
@@ -482,6 +526,8 @@ module ClaudeAgentSDK
             Process.kill('KILL', @process.pid)
             @process.value
           rescue StandardError => e
+            raise if e.is_a?(Async::TimeoutError)
+
             cleanup_errors << "force kill: #{e.message}"
           end
         rescue Errno::ESRCH
@@ -490,6 +536,10 @@ module ClaudeAgentSDK
       rescue Errno::ESRCH
         # Process already dead, ignore
       rescue StandardError => e
+        # An outer reactor deadline is cancellation, not a cleanup warning.
+        # Let close's ensure retain ownership and start fallback termination.
+        raise if e.is_a?(Async::TimeoutError)
+
         cleanup_errors << "process termination: #{e.message}"
       end
 
@@ -510,39 +560,65 @@ module ClaudeAgentSDK
     # pid-reuse-safe: while the waiter thread reports alive (not yet reaped),
     # the pid cannot have been recycled.
     def force_terminate_in_background(process, grace_seconds: 2)
-      return unless process&.alive?
+      return unless process
+
+      unless process.alive?
+        self.class.deregister_active_process(process)
+        return
+      end
 
       pid = process.pid
       begin
         Process.kill('TERM', pid)
+      rescue Errno::ESRCH
+        # The child exited before TERM; its waiter may still be reaping.
       rescue StandardError
-        return # ESRCH: already gone; EPERM: not ours to signal
+        return # EPERM etc.: retain the live child in the at_exit registry.
       end
 
       Thread.new do
-        sleep grace_seconds
         begin
-          Process.kill('KILL', pid) if process.alive?
+          unless process.join(grace_seconds)
+            begin
+              Process.kill('KILL', pid) if process.alive?
+            rescue Errno::ESRCH
+              # Still wait for the waiter when exit raced the signal.
+            end
+            process.join(grace_seconds)
+          end
         rescue StandardError
-          nil # died inside the grace window
+          nil # best-effort; retain ownership if termination/reaping failed
+        ensure
+          self.class.deregister_active_process(process) unless process.alive?
         end
       end
     end
 
     # Wait for the spawned process to exit, up to +timeout_seconds+. Polls
-    # @process.alive? rather than using stdlib Timeout.timeout, which raises
+    # process.alive? rather than using stdlib Timeout.timeout, which raises
     # across threads via Thread#raise and corrupts Async fiber-scheduler state
     # (close is always called inside an Async task). Yields to the current
     # Async task when one is active so the reactor keeps running.
-    def wait_process_with_timeout(timeout_seconds)
+    def wait_process_with_timeout(timeout_seconds, process = @process)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
       task = defined?(Async::Task) ? Async::Task.current? : nil
-      while @process.alive?
+      while process.alive?
         raise Timeout::Error if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
 
         task ? task.sleep(0.05) : sleep(0.05)
       end
-      @process.value
+      process.value
+    end
+
+    # Polls (via #wait_process_with_timeout) instead of
+    # Process::Waiter#join(timeout): under a Fiber scheduler Ruby 3.2's
+    # Thread#join ignores its timeout and never returns for a live thread
+    # (probed on 3.2.0; 3.3/3.4 honor it).
+    def process_exited_within?(process, seconds)
+      wait_process_with_timeout(seconds, process)
+      true
+    rescue Timeout::Error
+      false
     end
 
     def write(data)
@@ -559,9 +635,17 @@ module ClaudeAgentSDK
       # underlying stream and Ruby raises IOError("stream closed in another
       # thread") inside @stdin.write — the rescue below converts that into a
       # standard CLIConnectionError so callers see a clean shutdown error.
+      # A fiber parked here is NOT woken by that close, though (the async
+      # selector never learns the fd went away), so close wakes it with the
+      # same IOError via the registry below — see #wake_parked_fiber_writers.
+      writer = Fiber.current
       stdin = @stdin_mutex.synchronize do
         raise CLIConnectionError, 'ProcessTransport is not ready for writing' unless @ready && @stdin
 
+        # Registered in the same critical section as the snapshot, so a
+        # stdin detach (which nils @stdin under this lock) sees every writer
+        # that still holds the IO.
+        @inflight_writers[writer] = Fiber.scheduler
         @stdin
       end
 
@@ -572,25 +656,37 @@ module ClaudeAgentSDK
         @ready = false
         @exit_error = CLIConnectionError.new("Failed to write to process stdin: #{e}")
         raise @exit_error
+      rescue Exception => e # rubocop:disable Lint/RescueException -- cancellation is not a StandardError and must keep its class
+        # Cancellation (Async::Stop, InlineCancellation, a private deadline
+        # class) delivered while parked inside IO#write on a full pipe: the
+        # bytes already written stay on the pipe and nothing distinguishes
+        # an aborted frame from a complete one, so the next well-formed
+        # frame would be appended to a partial one and desync the protocol
+        # for the rest of the session. Poison the transport and re-raise the
+        # ORIGINAL exception: query.rb rescues Async::Stop by class, and
+        # cancellation semantics depend on it propagating unchanged.
+        # Recovery is a new session. Plain stores, like the StandardError
+        # branch above — no lock, so nothing here can suspend mid-unwind.
+        # (A writer already queued on IO#write's internal lock still
+        # appends its frame after the partial one; the session is dead
+        # either way, and every later write fails fast on @exit_error.)
+        @ready = false
+        @exit_error ||= CLIConnectionError.new(
+          "stdin write interrupted by #{exception_class_name(e)}: possible partial frame"
+        )
+        raise
+      ensure
+        @inflight_writers.delete(writer)
       end
     end
 
     def end_input
-      # Under @stdin_mutex like write/close (the transport's documented
-      # locking protocol; Python's end_input takes _write_lock too). The
-      # nil-guard must live INSIDE the critical section or the TOCTOU
-      # returns. NOTE: non-reentrant — close() inlines its own stdin
-      # handling and must never delegate here.
-      @stdin_mutex.synchronize do
-        return unless @stdin
-
-        begin
-          @stdin.close
-        rescue StandardError
-          # Ignore
-        end
-        @stdin = nil
-      end
+      # Same path as #close's stdin step: detach under @stdin_mutex (the
+      # transport's documented locking protocol; Python's end_input takes
+      # _write_lock too), then wake and close outside it.
+      shutdown_stdin
+    rescue StandardError
+      # Ignore
     end
 
     def read_messages(&block)
@@ -599,6 +695,10 @@ module ClaudeAgentSDK
       raise CLIConnectionError, 'Not connected' unless @process && @stdout
 
       json_buffer = ''
+      # True only when stdout reached EOF on its own. When the loop is cut
+      # short by close() (IOError) a partial trailing frame is expected and
+      # is not reported.
+      clean_eof = false
 
       begin
         # The limit bounds per-read allocation: a line longer than
@@ -663,6 +763,7 @@ module ClaudeAgentSDK
             next
           end
         end
+        clean_eof = true
       rescue IOError
         # Stream closed
       rescue StopIteration
@@ -672,10 +773,34 @@ module ClaudeAgentSDK
       # Check process completion. @process may already be nil (close() ran
       # concurrently and reset it) or already waited on (Errno::ECHILD on
       # double-wait). Both are non-fatal — the message loop just exits.
+      # Snapshot: a concurrent close() nils @process mid-wait.
+      process = @process
       returncode = nil
       termsig = nil
+      forced_exit = false
+      unreaped = false
       begin
-        status = @process&.value
+        # Bounded wait. The unbounded #value parked the read loop forever
+        # behind a CLI that closed stdout and then hung — no 'end' ever
+        # reached query()/receive_response. Past the grace period escalate
+        # like #close (TERM, then KILL) and report it as an error below: a
+        # child that outlives its stdout is wedged, whatever its exit code.
+        # The poll parks only this task (task.sleep) on a reactor.
+        if process && !process_exited_within?(process, EOF_EXIT_GRACE_SECONDS)
+          forced_exit = true
+          begin
+            Process.kill('TERM', process.pid)
+            unless process_exited_within?(process, EOF_TERM_GRACE_SECONDS)
+              Process.kill('KILL', process.pid)
+              # Even KILL can't reap a child stuck in uninterruptible kernel
+              # I/O; bound this last wait too rather than block on #value.
+              unreaped = !process_exited_within?(process, EOF_TERM_GRACE_SECONDS)
+            end
+          rescue Errno::ESRCH
+            # Exited between the check and the signal; value below is final.
+          end
+        end
+        status = process&.value unless unreaped
         # exitstatus is nil when the child died from a signal (OOM-kill
         # SIGKILL, SIGSEGV, ...) — that end-of-stream is a TRUNCATED response,
         # not a clean success. Python surfaces it as a negative returncode.
@@ -691,23 +816,54 @@ module ClaudeAgentSDK
       # reach (e.g. a Client abandoned without #disconnect, or direct transport
       # use). Idempotent — #close's own deregister becomes a harmless no-op, and
       # #close still sees @process (left set here) for its termination logic.
-      self.class.deregister_active_process(@process)
+      # A child that could not be reaped even after KILL stays registered:
+      # the at-exit safety net still owns it.
+      self.class.deregister_active_process(@process) unless unreaped
 
-      if termsig || (returncode && returncode != 0)
+      if forced_exit || termsig || (returncode && returncode != 0)
         # Wait briefly for stderr thread to finish draining
         @stderr_task&.join(1)
 
         stderr_text = @recent_stderr_mutex.synchronize { @recent_stderr.last(10).join("\n") }
         stderr_text = 'No stderr output captured' if stderr_text.empty?
 
+        message =
+          if unreaped
+            "Command did not exit within #{EOF_EXIT_GRACE_SECONDS}s of closing stdout, and could not be " \
+              'reaped even after SIGKILL'
+          elsif forced_exit
+            "Command did not exit within #{EOF_EXIT_GRACE_SECONDS}s of closing stdout; terminated by the SDK" +
+              (termsig ? " with signal #{termsig}" : '')
+          elsif termsig
+            "Command terminated by signal #{termsig}"
+          else
+            "Command failed with exit code #{returncode}"
+          end
+
         @exit_error = ProcessError.new(
-          termsig ? "Command terminated by signal #{termsig}" : "Command failed with exit code #{returncode}",
+          message,
           # Negative-signal exit_code mirrors Python's subprocess returncode.
           exit_code: termsig ? -termsig : returncode,
           stderr: stderr_text
         )
         raise @exit_error
       end
+
+      # A clean exit with a newline-less partial frame still buffered: the
+      # CLI (or whatever sits between it and us) cut a message short. The
+      # in-loop parse never sees it complete, so it used to be dropped
+      # silently — a missing ResultMessage with no error. Report it like
+      # the over-cap path does; a bare whitespace tail is not a frame, and
+      # once a concurrent #close has reset the transport (process nil) the
+      # stream was torn down deliberately and a cut-off tail is expected.
+      return unless clean_eof && process && !json_buffer.strip.empty?
+
+      raise CLIJSONDecodeError.new(
+        json_buffer,
+        StandardError.new(
+          "stdout ended mid-frame: #{json_buffer.bytesize} bytes buffered without a terminating newline"
+        )
+      )
     end
 
     def check_claude_version
@@ -789,6 +945,101 @@ module ClaudeAgentSDK
       end
     end
 
+    # Detach stdin under the same lock that guards #write's readiness
+    # check-and-snapshot — a concurrent writer (reactor fiber, or callback
+    # on a FiberBoundary thread) either sees nil (raises not-ready) or is
+    # already registered with its own snapshot — then wake and close
+    # OUTSIDE the lock: waking hands control to the writer, whose unwinding
+    # must not find the lock held, and the close may join a helper thread.
+    # Detach before waking, so no writer can start after the wake. Caller
+    # must NOT hold @stdin_mutex (non-reentrant). Raises what IO#close
+    # raises, except IOError (already closed).
+    def shutdown_stdin
+      stdin_io = @stdin_mutex.synchronize do
+        io = @stdin
+        @stdin = nil
+        io
+      end
+      return unless stdin_io
+
+      wake_parked_fiber_writers
+      close_stdin_io(stdin_io)
+    end
+
+    # Raise IOError into writer fibers of THIS thread's scheduler that are
+    # parked inside the stdin IO call (a full pipe: the CLI stopped
+    # reading). Closing the fd does not wake them — the async selector never
+    # learns the fd went away, so the writer stayed parked forever (Ruby
+    # 3.2/3.3/3.4, probed) and on Ruby 3.2 a close from another thread even
+    # delivered the IOError into the scheduler loop itself. The injected
+    # IOError is exactly what a plain-thread writer gets from the close, so
+    # both unwind through #write's StandardError branch into
+    # CLIConnectionError — the documented shutdown behavior. (Not
+    # Task#stop: that would cancel the writer's whole task, which may be
+    # the caller's own.) Scheduler#raise is the hand-off Task#stop and
+    # task timeouts use: the writer runs its unwinding now and this fiber
+    # resumes on the next reactor tick. Residual: a writer on another
+    # thread's reactor — or any fiber writer when stdin is closed off-reactor
+    # (e.g. Query's schedulerless fallback close) — cannot be reached from
+    # here: it stays parked on 3.3/3.4, and on 3.2 the close crashes its
+    # reactor with that IOError. The SDK's own writers share close's reactor.
+    def wake_parked_fiber_writers
+      scheduler = Fiber.scheduler
+      return unless scheduler
+
+      # to_a: one GVL-atomic snapshot — iterating the live Hash would let a
+      # concurrent insert raise in the writer. Newest first: a later writer
+      # is queued on IO#write's internal lock behind an earlier one, and
+      # waking the lock holder first makes its unlock hand the lock to the
+      # queued writer (scheduler.unblock) — a stale wakeup that would then
+      # cut that writer's NEXT suspension short. Woken first, the queued
+      # writer leaves the lock's wait queue in its own unwinding. Re-check
+      # registration before each raise: a writer that already unwound must
+      # not be interrupted wherever it is now.
+      @inflight_writers.to_a.reverse_each do |fiber, owner|
+        next unless @inflight_writers.key?(fiber)
+        next unless owner.equal?(scheduler) && !fiber.equal?(Fiber.current) && fiber.alive?
+
+        scheduler.raise(fiber, IOError, 'stdin closed while a write was in progress')
+      rescue FiberError
+        # Finished (or resumed) meanwhile — nothing to wake.
+      end
+    end
+
+    # Close the stdin write end without stalling the reactor. On Ruby 3.3+
+    # IO#close waits for threads blocked on the fd; called from a scheduler
+    # fiber that wait is a scheduler sleep the blocked thread's wakeup never
+    # resumes, so a FiberBoundary worker parked in #write on a full pipe
+    # hung close — and the whole reactor — forever (probed on 3.3.9 and
+    # 3.4.5; 3.2 does not wait). A plain helper thread has no scheduler:
+    # its close interrupts the parked writer (IOError "stream closed in
+    # another thread") and returns. Used only on a reactor with a
+    # plain-thread writer still registered; everything else closes inline.
+    # +wait+ false detaches the helper for #close's cancellation ensure,
+    # which must not block. Raises what IO#close raises, except IOError
+    # (already closed); a helper's own failure is dropped (best-effort).
+    def close_stdin_io(io, wait: true)
+      if Fiber.scheduler && @inflight_writers.value?(nil)
+        helper = Thread.new do
+          io.close
+        rescue StandardError
+          nil
+        end
+        helper.join if wait
+      else
+        io.close
+      end
+    rescue IOError
+      # Already closed, ignore
+    end
+
+    # An anonymous per-invocation cancellation class (FiberBoundary's
+    # cooperative timeouts, Query's private deadline) has no name; report
+    # its nearest named ancestor instead of "#<Class:0x...>".
+    def exception_class_name(error)
+      error.class.name || error.class.ancestors.find(&:name).name
+    end
+
     # Append a stderr line to the recent-stderr ring, dropping the oldest
     # entry once the buffer exceeds RECENT_STDERR_LINES_LIMIT. Used to surface the
     # last few lines in ProcessError when the CLI exits non-zero.
@@ -798,6 +1049,20 @@ module ClaudeAgentSDK
         @recent_stderr.shift if @recent_stderr.size > RECENT_STDERR_LINES_LIMIT
       end
     end
+
+    # The home directory for the well-known install probes, or nil when none
+    # is usable. Dir.home raises ArgumentError when HOME is unset and the uid
+    # has no passwd entry (docker --user in a minimal image), and returns an
+    # empty or relative HOME verbatim — probing under "" or a relative path
+    # would check files that are not where the user's install lives (and a
+    # relative hit would be spawned from options.cwd, i.e. a different file).
+    # SessionResume.home_dir applies the same rule.
+    def home_dir
+      home = Dir.home
+      home if File.absolute_path?(home)
+    rescue ArgumentError
+      nil
+    end
   end
 end
 

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -197,13 +197,15 @@ module ClaudeAgentSDK
 
     # -- Optional: list_session_summaries ----------------------------------
 
-    def check_list_session_summaries(fresh, has_list_sessions, has_delete)
+    def check_list_session_summaries(fresh, has_list_sessions, has_delete) # rubocop:disable Metrics/MethodLength
       # 14. persisted fold output round-trips through fold_session_summary.
       store = fresh.call
       summ_key = { 'project_key' => 'proj', 'session_id' => 'summ-sess' }
-      store.append(summ_key, [entry('timestamp' => '2024-01-01T00:00:00.000Z', 'customTitle' => 'first'),
+      store.append(summ_key, [entry('type' => 'user', 'timestamp' => '2024-01-01T00:00:00.000Z',
+                                    'customTitle' => 'first', 'message' => { 'content' => 'first prompt' }),
                               entry('timestamp' => '2024-01-01T00:00:01.000Z')])
-      store.append(summ_key, [entry('timestamp' => '2024-01-01T00:00:02.000Z', 'customTitle' => 'second')])
+      store.append(summ_key, [entry('type' => 'user', 'timestamp' => '2024-01-01T00:00:02.000Z',
+                                    'customTitle' => 'second', 'message' => { 'content' => 'later prompt' })])
       store.append({ 'project_key' => 'other', 'session_id' => 'elsewhere' },
                    [entry('timestamp' => '2024-01-01T00:00:00.000Z')])
 
@@ -219,9 +221,17 @@ module ClaudeAgentSDK
       end
 
       assert(summ['data'].is_a?(Hash), 'summary data must be a Hash')
+      # Independent expectations: refolding the adapter's own output alone
+      # accepts even an empty/stale sidecar and hides valid sessions in listings.
+      expected_data = { 'custom_title' => 'second', 'created_at' => 1_704_067_200_000,
+                        'first_prompt' => 'first prompt', 'first_prompt_locked' => true,
+                        'is_sidechain' => false }
+      assert_eq(summ['data'].slice(*expected_data.keys), expected_data,
+                'summary data must persist latest title and first timestamp/prompt across appends')
       refolded = SessionSummary.fold_session_summary(summ, summ_key, [entry('timestamp' => '2024-01-01T00:00:03.000Z')])
       assert_eq(refolded['session_id'], 'summ-sess', 'refold must preserve session_id')
       assert_eq(refolded['mtime'], summ['mtime'], 'fold must preserve prev mtime verbatim')
+      assert_eq(refolded['data'].slice(*expected_data.keys), expected_data, 'refold must preserve summary data')
 
       # Subagent appends must NOT affect the main session's summary.
       store.append(summ_key.merge('subpath' => 'subagents/agent-1'),