expect-pty 0.6.1 → 0.7.2

data/lib/expect/logging.rb

@@ -1,29 +1,32 @@
 # frozen_string_literal: true
 
+require "logger"
 require_relative "redactor"
 
-# 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
-# 接收日志、诊断和协议转发是三条独立通道；脱敏只改变前两条，不改变匹配或转发字节。
-class Expect
-  # @api private
+# 借用标准 Logger、接收记录 writer 和协议输出 writer，不接管它们的生命周期。
+# 脱敏只作用于诊断与接收记录，协议输出和匹配缓冲始终保留原始字节。
+module Expect
+  # 会话诊断、接收记录和协议转发的独立输出接口。
+  # 宿主 Session 初始化目标与过滤器状态，并提供 pid、fileno 作为诊断元数据。
+  # 三种输出各有边界：Logger 接收事件，transcript 接收脱敏字节，outputs 接收原协议字节。
   module Logging
-    # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-    attr_reader :log_output, :diagnostic_output
-
-    # 诊断目标仅借用；nil 沿用 stderr，Logger 使用 info/debug，回调接收冻结的事件 Hash。
-    # 先校验再冲刷旧流；校验或冲刷失败时保留旧目标，避免把暂存尾部交给错误的接收方。
-    def diagnostic_output=(target)
-      unless target.nil? || (target.respond_to?(:info) && target.respond_to?(:debug)) ||
-             target.respond_to?(:write) || target.respond_to?(:call)
-        raise ArgumentError, "diagnostic output must support info/debug, write or call, or be nil"
+    # 调用方提供的诊断 Logger 与原始接收记录 writer，均由调用方管理生命周期。
+    attr_reader :logger, :transcript
+
+    # Logger 自己决定级别、格式与失败策略；nil 禁用诊断，不隐式写入 stderr。
+    # 替换前先完成旧流脱敏，失败时仍保留旧 logger。
+    def logger=(target)
+      unless target.nil? || (target.respond_to?(:add) && target.respond_to?(:debug?))
+        raise ArgumentError, "logger must support add and debug?, or be nil"
       end
-      return if @diagnostic_output.equal?(target)
+      return if @logger.equal?(target)
 
       flush_diagnostics
-      @diagnostic_output = target
+      @logger = target
+      @diagnostic_redactors = {}
     end
 
-    # 秘密仅作用于本会话的日志和诊断，不改写匹配、stdout 显示或 listeners 的协议字节。
+    # 秘密仅作用于本会话的接收记录和诊断，不改写匹配或 outputs 的协议字节。
     # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
     def redact(*secrets)
       unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
@@ -31,69 +34,52 @@ class Expect
       end
 
       @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
-      @log_redactor.patterns = @secrets if @log_redactor
+      @transcript_redactor.patterns = @secrets if @transcript_redactor
       @diagnostic_redactors.each_value { |redactor| redactor.patterns = @secrets }
-      connection
+      self
     end
 
-    # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
-    def log_output=(target)
-      unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
-        raise ArgumentError, "log output must support write or call, or be nil"
-      end
-
-      replace_log(target)
-    end
-
-    # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
-    def log_to(target = nil, mode: "a", &block)
-      raise ArgumentError, "provide a log target or a block, not both" if block && target
+    # 接收记录只采用 write 协议；文件打开、权限和关闭由调用方管理。
+    def transcript=(target)
+      raise ArgumentError, "transcript must support write, or be nil" unless target.nil? || target.respond_to?(:write)
+      return if @transcript.equal?(target)
 
-      target = block if block
-      if target.respond_to?(:to_path) || target.is_a?(String)
-        raise ArgumentError, "log mode must be a or w" unless %w[a w].include?(mode)
-
-        # 先交付旧过滤尾部，再允许新路径截断；同一文件不能在截断后被旧句柄写回。
-        flush_log
-        # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
-        replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
-      else
-        raise ArgumentError, "provide a log target or a block" unless target
-
-        self.log_output = target
-      end
+      flush_transcript
+      @transcript = target
+      @transcript_redactor = nil
     end
 
-    # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
-    # 启用脱敏后可能暂存末尾字节，因此一次调用不保证触发一次日志写入或回调。
-    def write_log(*objects)
-      target = log_output
+    # 向接收记录补写内容，不发送给子进程或 outputs；脱敏尾部可能延迟交付，返回 nil。
+    def write_transcript(*objects)
+      target = transcript
       return unless target
 
       data = objects.map { |object| object.to_s.b }.join
       if @secrets
-        @log_redactor ||= Redactor.new(@secrets)
-        data = @log_redactor.append(data)
+        @transcript_redactor ||= Redactor.new(@secrets)
+        data = @transcript_redactor.append(data)
         return if data.empty?
       end
-      target.respond_to?(:call) ? target.call(data) : emit(target, data)
+      emit(target, data)
+      nil
     end
 
-    # 返回监听器列表副本，避免外部原地修改转发关系。
-    def listeners = @listeners.dup
+    # 返回副本，避免外部原地修改转发关系；stdout 与其他 writer 使用相同协议。
+    def outputs = @outputs.dup
 
-    # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
-    def listeners=(outputs)
-      outputs = Array(outputs)
-      raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
+    # 先校验整个数组再替换，失败时保留原输出图。
+    def outputs=(targets)
+      unless targets.is_a?(Array) && targets.all? { |target| target.respond_to?(:write) }
+        raise ArgumentError, "outputs must be an Array of writers"
+      end
 
-      @listeners = outputs.dup
+      @outputs = targets.dup
     end
 
-    # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
+    # 原样转发协议字节，接收记录在读取时单独写入。
+    # @api private
     def propagate(data)
-      emit($stdout, data) if log_stdout?
-      @listeners.each { |listener| emit(listener, data) } if log_listeners?
+      @outputs.each { |output| emit(output, data) }
     end
 
     private
@@ -114,45 +100,33 @@ class Expect
       target.flush if target.respond_to?(:flush)
     end
 
-    # 字节诊断在 inspect 转义之前过滤；缓冲快照可能只含秘密中间片段，启用脱敏时不展开。
-    def trace_data(event, data, level:)
-      if @secrets
-        return trace("buffer [FILTERED]", level:, event:) if event == :buffer
+    # 字节诊断在 inspect 转义之前过滤，发送与接收各自保留分片状态。
+    def trace_data(event, data)
+      return unless logger&.debug?
 
+      if @secrets
         redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
         data = redactor.append(data)
         return if data.empty?
       end
-      trace("#{event} #{data.inspect}", level:, event:)
+      trace("#{event} #{data.inspect}", severity: Logger::DEBUG, event:)
     end
 
-    # 诊断与接收字节日志分开；回调元数据不含会话对象，避免格式化时意外展开原始缓冲。
-    def trace(message, level: 1, event: :matched)
-      return unless debug_level >= level
-
-      severity = level == 1 ? :info : :debug
-      target = diagnostic_output
-      if target.respond_to?(:info) && target.respond_to?(:debug)
-        target.public_send(severity, "#{inspect}: #{message}")
-      elsif target.respond_to?(:call)
-        target.call({ event:, level: severity, pid:, fd: fileno, message: message.freeze }.freeze)
-      elsif target
-        emit(target, "#{inspect}: #{message}\n")
-      else
-        warn("#{inspect}: #{message}")
-      end
+    # 向标准 Logger 提交不可变事件，不包含会话对象；格式化由 logger 完成。
+    def trace(message, severity: Logger::INFO, event: :matched)
+      logger&.add(severity, { event:, pid:, fd: fileno, message: message.freeze }.freeze, "Expect")
     end
 
     # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
-    def flush_log
+    def flush_transcript
       loop do
-        return unless @log_redactor && log_output
+        return unless @transcript_redactor && transcript
 
-        data = @log_redactor.finish
+        data = @transcript_redactor.finish
         return if data.empty?
 
-        log_output.respond_to?(:call) ? log_output.call(data) : emit(log_output, data)
-        # 回调可能轮换目标并追加新尾部；先结束它，再允许外层截断文件或关闭日志。
+        emit(transcript, data)
+        # writer 可能重入并追加尾部；交接前仍归当前记录流。
       end
     end
 
@@ -171,31 +145,11 @@ class Expect
           next if data.empty?
 
           delivered = true
-          trace("#{name} #{data.inspect}", level: 2, event: name)
+          trace("#{name} #{data.inspect}", severity: Logger::DEBUG, event: name)
         end
         # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
         break unless delivered
       end
     end
-
-    # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
-    def replace_log(target, owned: false)
-      # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
-      return target if log_output.equal?(target)
-
-      Cleanup.on_failure(-> { target.close if owned && target && !target.closed? }) do
-        flush_log
-        # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
-        next target if log_output.equal?(target)
-
-        previous = @resources.owned_log
-        previous.close if previous && !previous.closed?
-        # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
-        @resources.owned_log = owned ? target : nil
-        @log_output = target
-        @log_redactor = nil
-        target
-      end
-    end
   end
 end

data/lib/expect/matcher.rb

@@ -1,28 +1,30 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
   # 调度只在扫描、回调和 IO 操作之间检查期限，不强行中断用户代码或单次正则计算。
   # @api private
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
-    def initialize(patterns, timeout, deadline: nil)
+    def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false)
       @patterns = patterns.finalize!
-      @sessions = patterns.sessions.map { |connection| Session.for(connection) }
-      @groups = patterns.groups.map { |connections, entries| [connections.map { |c| Session.for(c) }, entries] }
+      @sessions = patterns.sessions
+      @groups = patterns.groups
+      @consume = consume
+      @reset_timeout_on_read = reset_timeout_on_read
       @timeout = Expect.duration(timeout)
       # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
       @hard_deadline = deadline
       @deadline = next_deadline
       @handled_eof = {}.compare_by_identity
-      @stalled_matches = {}
+      @stalled_matches = {}.compare_by_identity
       @polled = false
       @expired_eof_continuation = false
     end
 
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
     def run
-      @relay_buffers = {}
+      @relay_buffers = {}.compare_by_identity
       @sessions.each do |session|
         buffer = session.interaction_buffer
         if buffer
@@ -124,8 +126,8 @@ class Expect
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
       previous_buffer = session.buffer
-      result = session.record_match(pattern, position)
-      action = pattern.call(session.connection)
+      result = session.record_match(pattern, position, consume: @consume)
+      action = pattern.call(session)
       return result unless continuing?(action)
 
       # 回调未改变缓冲时暂停当前模式，等待缓冲变化后再匹配，避免原地空转。
@@ -133,9 +135,9 @@ class Expect
         stalled = (@stalled_matches[session] ||= { buffer: previous_buffer, patterns: [] })
         stalled[:patterns] << pattern
       end
-      @deadline = next_deadline if action == CONTINUE
+      @deadline = next_deadline if CONTINUE.equal?(action)
       # 总期限到达时回主循环先派发已知 EOF；仅相对期限延续原有立即超时语义。
-      return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired? && !hard_expired?
+      return handle_timeout if CONTINUE_WITHOUT_RESET.equal?(action) && expired? && !hard_expired?
 
       :retry
     end
@@ -149,14 +151,15 @@ class Expect
     def handle_eof(session)
       result = session.record_eof
       @handled_eof[session] = true
-      actions = @patterns.eof_patterns_for(session.connection).map { |pattern| pattern.call(session.connection) }
+      actions = @patterns.eof_patterns_for(session).map { |pattern| pattern.call(session) }
       return result unless actions.any? { |action| continuing?(action) }
 
-      @deadline = next_deadline if actions.include?(CONTINUE)
+      reset_timeout = actions.any? { |action| CONTINUE.equal?(action) }
+      @deadline = next_deadline if reset_timeout
       return result if @handled_eof.size == @sessions.size
 
       # 期限已过时不再扫描文本，但先派发已知 EOF；最后一个源结束不能被误报为超时。
-      @expired_eof_continuation = !actions.include?(CONTINUE) && expired?
+      @expired_eof_continuation = !reset_timeout && expired?
 
       :retry
     end
@@ -200,7 +203,7 @@ class Expect
           return session.record_error(error)
         end
         @stalled_matches.delete(session) if data
-        @deadline = next_deadline if data && session.reset_timeout_on_read?
+        @deadline = next_deadline if data && @reset_timeout_on_read
       end
       :retry
     end
@@ -209,7 +212,7 @@ class Expect
     def active_sessions = @sessions.reject { |session| @handled_eof.key?(session) }
 
     # 只有约定的继续符号会驱动下一轮，普通回调返回值不会改变等待流程。
-    def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
+    def continuing?(action) = CONTINUE.equal?(action) || CONTINUE_WITHOUT_RESET.equal?(action)
 
     # 使用单调时钟计算期限；nil 一直表示无限等待，不受系统时间调整影响。
     # 每次重置都重新与总期限取较早者，避免连续输入或继续回调无限推迟结束。
@@ -225,10 +228,10 @@ class Expect
     def remaining = @deadline && [@deadline - Expect.monotonic, 0].max
 
     # 判断有限期限是否已到达；无限等待不会触发超时。
-    def expired? = @deadline && Expect.monotonic >= @deadline
+    def expired? = !@deadline.nil? && Expect.monotonic >= @deadline
 
     # 绝对总期限不受接收数据和 continue 重置；已知 EOF 仍按原顺序派发。
-    def hard_expired? = @hard_deadline && Expect.monotonic >= @hard_deadline
+    def hard_expired? = !@hard_deadline.nil? && Expect.monotonic >= @hard_deadline
 
     # select 失败时无法归属单个源，只更新仍监听的会话；已派发 EOF 的结果保持不变。
     def record_error(error)
@@ -239,8 +242,8 @@ class Expect
     # 已到总期限仍通知超时回调，但不接受继续请求，且不消费尚未匹配的字节。
     def handle_timeout
       results = active_sessions.map { |session| session.record_error(:timeout) }
-      action = @patterns.timeout_pattern&.call(active_sessions.map(&:connection))
-      return results.first unless action == CONTINUE && !hard_expired?
+      action = @patterns.timeout_pattern&.call(active_sessions)
+      return results.first unless CONTINUE.equal?(action) && !hard_expired?
 
       @deadline = next_deadline
       @polled = false

data/lib/expect/pattern.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 一个已编号的文本模式或事件及其回调；匹配结果统一使用字节偏移，便于精确消费 IO 缓冲。
   # @api private
   Pattern = Data.define(:number, :value, :callback) do
+    # 复制字符串模式；Regexp 和 callable 只引用，不取得外部对象的生命周期。
     def initialize(value:, number: nil, callback: nil)
       super(value: value.is_a?(String) ? value.b.freeze : value, number:, callback:)
     end

data/lib/expect/pattern_list.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
   # 分组结构直接决定 Matcher 的“声明组 → 会话 → 模式”优先级，不能按匹配位置重排。
   class PatternList
@@ -103,7 +103,7 @@ class Expect
 
     # 会话的业务相等性不能合并不同读取源；来源对象及排列都必须相同。
     def same_sessions?(previous, sessions)
-      previous && previous.size == sessions.size &&
+      !previous.nil? && previous.size == sessions.size &&
         previous.each_with_index.all? { |session, index| session.equal?(sessions[index]) }
     end
 
@@ -113,11 +113,11 @@ class Expect
       Pattern.new(number: @number, value:, callback:)
     end
 
-    # 拒绝空来源和非 Expect 对象，在任何 IO 读取之前暴露调用错误。
+    # 拒绝空来源和非 Session 对象，在任何 IO 读取之前暴露调用错误。
     def validate_sessions!(sessions)
-      return if !sessions.empty? && sessions.all?(Expect)
+      return if !sessions.empty? && sessions.all?(Session)
 
-      raise ArgumentError, "patterns require Expect sessions; specify from: for class-level waits"
+      raise ArgumentError, "patterns require Session objects; specify from: for class-level waits"
     end
   end
 end

data/lib/expect/redactor.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
   # 不依赖会话或 IO；每个日志目标或诊断方向使用独立实例。

data/lib/expect/relay.rb

@@ -1,29 +1,30 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 一次转接的共同读写循环；发送游标留在源会话中，调用结束后仍可继续。
   # 本对象只暂借未处理输入；读缓冲、发送进度与转义回调分开保存，避免重入时重复交付。
   # @api private
   class Relay
+    # 只串行化来源归属交接；Session 的其他操作仍须由调用方避免并发修改。
     OWNERSHIP_MUTEX = Mutex.new
     private_constant :OWNERSHIP_MUTEX
 
     # 这里只校验参数；run 取得所有来源后才转移缓冲，不关闭或接管任何外部 IO。
     def initialize(sessions, timeout)
-      @sessions = sessions.uniq
+      @sessions = sessions.uniq(&:object_id)
       @active = @sessions.dup
       period = Expect.duration(timeout)
       @deadline = period && (Expect.monotonic + period)
       @token = Object.new
-      @buffers = {}
-      @previous = {}
+      @buffers = {}.compare_by_identity
+      @previous = {}.compare_by_identity
     end
 
     # 每轮先处理转义和已排队输出，再共同选择读写；停止返回来源会话，总期限到达返回 nil。
     # 真实 IO 的写入由非阻塞游标推进，用户日志和回调仍同步执行，须由调用方保证及时返回。
     def run
       prepare_sources
-      outputs.each(&:restart_timeout)
+      pending_writes.each(&:restart_timeout)
       polled = false
       loop do
         stopped, idle, queued = dispatch_sources
@@ -53,15 +54,13 @@ class Expect
 
         if (callback = session.relay_callback)
           session.relay_callback = nil
-          return [session, idle, queued] unless callback.first&.call
+          return [session, idle, queued] unless callback.call
         end
 
-        result = Interaction.relay_buffer(session, @buffers, final: session.eof?) do |data|
-          session.queue_output(data)
-        end
-        return [session, idle, queued] unless result
+        result = Interaction.queue_input(session, @buffers.fetch(session), final: session.eof?)
+        return [session, idle, queued] if result == :stopped
 
-        if result == :pending
+        if result == :queued
           queued = true
           next
         end
@@ -72,14 +71,14 @@ class Expect
         callback = session.sequences[:eof]
         return [session, idle, queued] unless callback&.call
 
-        @active.delete(session)
+        @active.delete_if { |active| active.equal?(session) }
       end
       [nil, idle, queued]
     end
 
     # 共同等待来源与目标，每轮读每个就绪来源一次；EINTR 返回原期限循环。
     def select_and_read(progress)
-      pending = outputs
+      pending = pending_writes
       readers = read_sources(pending)
       deadlines = [@deadline, *pending.map(&:deadline)].compact
       remaining = deadlines.empty? ? nil : [deadlines.min - Expect.monotonic, 0].max
@@ -150,13 +149,13 @@ class Expect
     end
 
     # 只收集尚未完成的目标，供共同 select 以及最早写入期限计算使用。
-    def outputs = @sessions.flat_map(&:relay_outputs).reject(&:done?)
+    def pending_writes = @sessions.flat_map(&:pending_writes).reject(&:done?)
 
     # 每个目标每轮最多推进一个片段；移除已完成游标，并告知主循环是否值得立即继续轮询。
     def advance_outputs(check_timeout: true)
       progress = false
       @sessions.each do |session|
-        pending = session.relay_outputs
+        pending = session.pending_writes
         pending.each { |output| progress = output.advance(check_timeout:) || progress }
         pending.reject!(&:done?)
       end
@@ -164,15 +163,17 @@ class Expect
     end
 
     # 转接总期限不因持续输入或某个目标的写入进展而重置。
-    def expired? = @deadline && Expect.monotonic >= @deadline
+    def expired? = !@deadline.nil? && Expect.monotonic >= @deadline
 
     # 背压源暂停吸收新输入，限制排队增长；作为写入目标的会话仍需读取以解除双向等待。
     def read_sources(pending)
       # 输出目标可能也在等待我们读取；这些来源即使有待发送数据也必须继续排空。
       targets = pending.filter_map do |output|
-        Session.for(output.target) if output.target.is_a?(Expect)
+        output.target if output.target.is_a?(Session)
+      end
+      sources = @active.reject do |session|
+        session.pending_output? && targets.none? { |target| target.equal?(session) }
       end
-      sources = @active.reject { |session| session.pending_output? && !targets.include?(session) }
       (sources + targets).uniq { |session| session.to_io.object_id }.reject(&:eof?)
     end
 
@@ -180,7 +181,7 @@ class Expect
     # 目标的写期限更早到达时保留 WriteTimeout 语义，不能被转接的普通超时掩盖。
     def finish_timeout(idle)
       # 调度延迟可能让两种期限均已到达，仍按先到的期限决定结果。
-      outputs.each { |output| output.check_timeout! if output.deadline && output.deadline < @deadline }
+      pending_writes.each { |output| output.check_timeout! if output.deadline && output.deadline < @deadline }
       idle.each do |session|
         next if session.pending_output?
 

data/lib/expect/relay_writer.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
   # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
   # @api private
   class RelayWriter
+    # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
     attr_reader :target, :deadline
 
     # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
@@ -19,13 +20,13 @@ class Expect
     # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
     # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
     def restart_timeout
-      period = target.write_timeout if target.is_a?(Expect)
+      period = target.write_timeout if target.is_a?(Session)
       @deadline = period && (Expect.monotonic + period)
     end
 
     # 真实 IO 可参与共同 select；自定义可写对象返回 nil，沿用其同步 write/flush 协议。
     def io
-      return target.writer if target.is_a?(Expect)
+      return target.writer if target.is_a?(Session)
 
       target if target.is_a?(IO)
     end
@@ -37,7 +38,7 @@ class Expect
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 游标、短写、flush 和期限按单个目标推进。
     def advance(check_timeout: true)
       return false if done?
-      raise IOError, "closed Expect session" if target.is_a?(Expect) && target.closed?
+      raise IOError, "closed Expect session" if target.is_a?(Session) && target.closed?
 
       if @offset < @data.bytesize
         bytes = @data.byteslice(@offset, READ_SIZE)

data/lib/expect/result.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 一次等待的不可变快照；session 与 error 只引用来源和原始异常，不取得其所有权。
   # 文本和捕获值单独复制冻结，后续读取或调用者修改输入不会改变结果。
   # @!method self.new(**fields)