expect-pty 0.3.1 → 0.3.3

data/docs/RELEASING.md

@@ -4,8 +4,8 @@
 
 ## 准备版本
 
-1. 更新 `lib/expect/version.rb` 的 `Expect::VERSION`，例如 `0.3.1`。
-2. 把 `CHANGELOG.md` 的 `Unreleased` 内容移到对应版本标题下，例如 `## 0.3.1 - 2026-09-26`；可以保留空的 `Unreleased` 标题。
+1. 更新 `lib/expect/version.rb` 的 `Expect::VERSION`，例如 `0.3.3`。
+2. 把 `CHANGELOG.md` 的 `Unreleased` 内容移到对应版本标题下，例如 `## 0.3.3 - 2026-09-27`；可以保留空的 `Unreleased` 标题。
 3. 提交源码，发布时工作区必须干净。若同时发布 GitHub Release，还需推送到 `main`，远端 `main` 必须包含该提交，已有同名标签必须指向该提交。
 
 发布脚本只接受正式版 `X.Y.Z`；未归档的变更会阻止发布。
@@ -22,6 +22,8 @@ ruby script/release.rb --rubygems-only
 
 默认执行 `script/ci` 的检查、完整测试、构建和隔离安装验证，构建包保存在 `tmp/ci/expect-pty-版本号.gem`。随后复制到 `tmp/release/版本号/candidate-*/` 的独占目录，核对包内文件并生成发布说明和校验文件。该副本贯穿后续发布，目录会保留供失败重试。正式发布前再次确认源码未变，上传 RubyGems 后下载远端包核对 SHA256。
 
+正式发布逐个核对包内普通文件在目标 Git 提交中的存在性、原始字节和执行权限，同时核对 gemspec 的安装元数据及主页。`git status` 为空不能替代这一检查：忽略规则可能隐藏被 glob 收入包的本地文件，`assume-unchanged` 和 `core.filemode` 也可能隐藏差异。候选包必须与已提交源码一致。
+
 `--dry-run` 只做本地验证，可在提交前使用。它仍要求版本号和发布说明完整。
 
 ## 同时发布 GitHub Release
@@ -40,9 +42,9 @@ ruby script/release.rb
 GitHub Runner 不会继承本机的 Gem 登录状态。要在 Actions 发布 RubyGems，需在仓库的 Settings → Secrets and variables → Actions 中配置 `RUBYGEMS_API_KEY`，使用具有 `Push rubygem` 权限的发布 Key。
 
 ```sh
-git tag -a v0.3.1 -m 'Release v0.3.1'
-git push origin v0.3.1
-gh workflow run release.yml --ref v0.3.1 --repo gatework/expect-ruby
+git tag -a v0.3.3 -m 'Release v0.3.3'
+git push origin v0.3.3
+gh workflow run release.yml --ref v0.3.3 --repo gatework/expect-ruby
 ```
 
 也可以在 Actions → Release → Run workflow 选择对应版本标签。工作流仅支持手动触发，避免本地发布时出现第二次并发上传。
@@ -56,7 +58,7 @@ gh workflow run release.yml --ref v0.3.1 --repo gatework/expect-ruby
 保留脚本输出的 `Artifact` 路径，用该候选 Gem 重试发布；更换 RubyGems 工具版本或重新构建可能得到不同字节，同一个版本不得覆盖已有内容。也可以直接指定从 CI 或 Release 下载的原包：
 
 ```sh
-ruby script/release.rb --rubygems-only --artifact tmp/ci/expect-pty-0.3.1.gem
+ruby script/release.rb --rubygems-only --artifact tmp/ci/expect-pty-0.3.3.gem
 ```
 
 将示例路径替换为实际输出的 `Artifact` 路径。`--artifact` 会跳过构建和测试，但仍核对包与当前源码是否一致；需要同时恢复 GitHub Release 时去掉 `--rubygems-only`。

data/docs/VERIFICATION.md

@@ -1,5 +1,29 @@
 # 验证记录
 
+## 模块审查、资源清理与正则输入复用（2026-09-27）
+
+基线为 `b9fc077`，以下为 0.3.3 发布准备前的源码审查记录。覆盖会话、配置、模式声明与定位、匹配结果及期限、资源所有权、日志、终端、人工接管、转接恢复、示例、发布和打包模块。修复工厂/构造失败后的子进程回收、部分句柄清理、原始异常保留、EOF 继续期限和发布包提交来源验证；新行为均有先失败后通过的回归。EOF 补充多源同时结束和重置期限用例，保留已知 EOF 的派发顺序。
+
+日志与终端方法拆入独立能力文件，公共入口保持 `expect/pty`；打包检查确认两文件随 Gem 分发。正则输入复用通过冻结输入、编码分片、二进制、字节偏移及匹配/转接回归，实测数据见 [性能基准](PERFORMANCE.md#正则输入复用验证2026-09-27)。
+
+| 当前运行环境 | 完整 `bash script/ci` |
+| --- | --- |
+| macOS arm64，Ruby 4.0.6，Bundler 4.0.17，原工作区 | 269 项 / 1,356 断言，0 失败、错误、跳过；RuboCop 51 文件无违规 |
+| macOS arm64，同一运行时，隔离 worktree | 同上；从基线加本轮补丁及新增文件重建 |
+| Linux aarch64，Ruby 3.2.11，Bundler 4.0.17，独立容器副本 | 同上；冻结开发锁文件，容器独立安装依赖 |
+
+三次均完成对话示例、三组基准 smoke、Gem 构建、普通 RubyGems 与最小 Bundler 应用的隔离安装及真实 PTY 对话。另检查包内 69 个文件及新增模块，无构建目录或日志；工作流 actionlint 通过（未启用 shellcheck），发布与示例 `--help` 正常。macOS 构建仍有宿主 RDoc 7/8 重复常量警告，退出状态为 0。
+
+发布测试使用临时 Git 仓库，验证合法包通过，忽略文件、`assume-unchanged` 隐藏内容、忽略执行权限变化及主页元数据不一致均被拒绝，未连接发布服务。审查时版本仍为 0.3.2，改动位于 `Unreleased`，这些本地检查不代替发布验证；当时未运行真实 SSH、远端 CI 或 Ruby 3.3/3.4，也未提交、推送或发布。0.3.3 的远端平台结果以发布提交对应的 GitHub Actions 为准，以下历史结果不作为本轮验证证据。
+
+## 配置并发与模块审查改进（2026-09-26）
+
+当前工作树在既有未提交的匹配、转接和清理改动上，增加 `configure` 的串行读改写与回归测试：旧实现的并发用例先失败，修复后通过；嵌套调用显式抛出 `ThreadError`，不会陷入死锁或发布部分配置。`read_available` 的裁剪选择改为显式参数，转接调用明确禁止裁剪其待处理缓冲。RuboCop 对生产代码启用分支复杂度检查，既有状态机只在对应方法局部豁免；补充内部调用契约、贡献指南、issue/PR 模板与安全说明。
+
+macOS arm64、Ruby 4.0.6、Bundler 4.0.17 下执行 `bash script/ci`：249 项测试、1,242 条断言，0 失败、错误或跳过；RuboCop 检查 49 个文件无违规。对话示例、三组基准 smoke、Gem 构建、普通 RubyGems 与 Bundler 隔离安装及真实 PTY 对话均通过。构建时本机 RDoc 7/8 重复常量警告仍存在，但命令成功完成。
+
+本轮未运行 Linux/Ruby 3.2、远端 CI 或真实 SSH；未提交、推送或发布。下文历史结果不作为本轮检查证据。
+
 ## 0.3.0 发布前复核（2026-09-26）
 
 以 0.2.0 为基线导入源码更新，发布前增加 8 项回归，覆盖退出正则切换、同规则跨次匹配、待发送恢复、跨次 CRLF、转义回调内匹配与异常尾部恢复、嵌套写入超时进度。新用例先在修复前失败，再验证修复；仅内部转义处理器的两项测试随职责调整更新调用方式。

data/examples/kibitz/kibitz.rb

@@ -51,6 +51,7 @@ module Kibitz
     value
   end
 
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- CLI 建连、终端接管和 ensure 清理共享一次生命周期。
   def self.run(argv, input: $stdin, output: $stdout)
     options = { escape: ESCAPE }
     parser = OptionParser.new do |opts|
@@ -134,6 +135,7 @@ module Kibitz
     File.unlink(socket_path) if socket_path && File.socket?(socket_path)
     Dir.rmdir(directory) if directory && Dir.exist?(directory)
   end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 end
 
 exit Kibitz.run(ARGV) if $PROGRAM_NAME == __FILE__

data/expect-pty.gemspec

@@ -15,7 +15,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir[
     "lib/**/*.rb", "examples/**/*.rb", "examples/**/*.md", "docs/**/*.md", "benchmark/**/*.rb",
     "test/**/*.rb", "test/**/*.sh", "test/**/*.md", "Gemfile", "Rakefile",
-    ".rubocop.yml", "expect-pty.gemspec", "README.md", "LICENSE", "CHANGELOG.md", "script/ci", "script/release.rb"
+    ".rubocop.yml", "expect-pty.gemspec", "README.md", "CONTRIBUTING.md", "LICENSE", "CHANGELOG.md",
+    "script/ci", "script/release.rb"
   ]
   spec.require_paths = ["lib"]
   # 显式声明可独立升级的标准库 gem，供应用的 Bundler 解析完整运行时依赖。

data/lib/expect/interaction.rb

@@ -8,7 +8,7 @@ class Expect
   REGEXP_ESCAPE_HISTORY_LIMIT = 65_536
   private_constant :REGEXP_ESCAPE_HISTORY_LIMIT
 
-  # Presents remote text on a raw local terminal without changing existing CRLF sequences.
+  # 在 raw 本地终端显示远端文本，补齐 LF 所需的 CR，同时保留已有 CRLF。
   class InteractOutput
     def initialize(target)
       @target = target
@@ -87,14 +87,20 @@ class Expect
 
   # 转发一个会话的待处理缓冲并剔除转义；返回 false 表示应结束整个转接。
   # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 转义匹配、前缀暂存和回调消费属于同一轮扫描。
   def self.relay_buffer(session, buffers, final: false)
     buffer = buffers.fetch(session)
     loop do
       sequences = session.__send__(:sequences).except(:eof)
       history = session.__send__(:relay_history)
+      text = nil
+      utf8_regexp = false
       matches = sequences.filter_map do |key, handler|
         if key.is_a?(Regexp)
-          position = Pattern.new(value: key).locate(history + buffer, final: final)
+          # 仅在本轮扫描复用组合文本；回调可能更换规则或消费缓冲，下一轮必须重新构造。
+          text ||= history + buffer
+          utf8_regexp ||= key.fixed_encoding? && key.encoding == Encoding::UTF_8
+          position = Pattern.new(value: key).locate(text, final: final)
           if position
             offset, length, = position
             raise ArgumentError, "escape regexp must consume at least one byte" if length.zero?
@@ -148,12 +154,12 @@ class Expect
         data = buffer.byteslice(0, count)
         block_given? ? yield(data) : session.__send__(:propagate, data)
       end
-      if sequences.keys.any?(Regexp)
+      if text
         history << buffer.byteslice(0, count)
         limit = session.buffer_limit || REGEXP_ESCAPE_HISTORY_LIMIT
         if history.bytesize > limit
           history.replace(history.byteslice(-limit, limit))
-          if sequences.keys.any? { |key| key.is_a?(Regexp) && key.fixed_encoding? && key.encoding == Encoding::UTF_8 }
+          if utf8_regexp
             # 窗口可能从 UTF-8 续字节开始；丢弃不完整的首字符后再交给固定编码正则。
             history.slice!(0) while (byte = history.getbyte(0)) && (0x80..0xBF).cover?(byte)
           end
@@ -163,6 +169,7 @@ class Expect
       return block_given? && count.positive? ? :pending : true
     end
   end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   private_class_method :relay_buffer
 
@@ -189,7 +196,7 @@ class Expect
 
   private :interact_source, :queue_output
 
-  # Only interact knows which stream is the local keyboard. Generic interconnect leaves terminals alone.
+  # 只有 interact 知道哪个流是本地键盘；通用 interconnect 不修改终端模式。
   def prepare_interact_terminal(source)
     return unless source.raw_terminal? && source.tty?
 
@@ -197,7 +204,7 @@ class Expect
     state = [io, io.console_mode]
     io.raw!
     state
-  rescue Exception # rubocop:disable Lint/RescueException -- Restore a partially changed terminal on interrupts.
+  rescue Exception # rubocop:disable Lint/RescueException -- 中断时也恢复可能已部分修改的终端。
     restore_interact_terminal(state)
     raise
   end

data/lib/expect/logging.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
+class Expect
+  # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
+  attr_reader :log_output
+
+  # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
+  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
+
+    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)
+
+      # 库打开的文件由 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
+  end
+
+  # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
+  def write_log(*objects)
+    target = log_output
+    return unless target
+
+    data = objects.map { |object| object.to_s.b }.join
+    target.respond_to?(:call) ? target.call(data) : emit(target, data)
+  end
+
+  # 返回监听器列表副本，避免外部原地修改转发关系。
+  def listeners = @listeners.dup
+
+  # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
+  def listeners=(outputs)
+    outputs = Array(outputs)
+    raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
+
+    @listeners = outputs.dup
+  end
+
+  private
+
+  # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
+  def propagate(data)
+    emit($stdout, data) if log_stdout?
+    @listeners.each { |listener| emit(listener, data) } if log_listeners?
+  end
+
+  # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
+  def emit(target, data)
+    offset = 0
+    while offset < data.bytesize
+      count = target.write(data.byteslice(offset..))
+      unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
+        raise IOError, "write must return the number of accepted bytes"
+      end
+
+      offset += count
+    end
+    target.flush if target.respond_to?(:flush)
+  end
+
+  # 按诊断级别向 stderr 输出会话标识和消息。
+  def trace(message, level: 1)
+    warn("#{inspect}: #{message}") if debug_level >= level
+  end
+
+  # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
+  def replace_log(target, owned: false)
+    previous = log_output
+    # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
+    return target if previous.equal?(target)
+
+    previous.close if @resources.owned_log && previous && !previous.closed?
+    # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
+    @resources.owned_log = owned ? target : nil
+    @log_output = target
+    target
+  rescue Exception # rubocop:disable Lint/RescueException -- 替换失败时仍释放刚打开的文件。
+    target.close if owned && target && !target.closed?
+    raise
+  end
+end

data/lib/expect/matcher.rb

@@ -12,6 +12,7 @@ class Expect
       @handled_eof = []
       @stalled_matches = {}
       @polled = false
+      @expired_eof_continuation = false
     end
 
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
@@ -30,10 +31,12 @@ class Expect
       end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
-        result = if (matched = find_match)
+        result = if !@expired_eof_continuation && (matched = find_match)
                    handle_match(*matched)
                  elsif (session = unhandled_eof)
                    handle_eof(session)
+                 elsif @expired_eof_continuation
+                   handle_timeout
                  else
                    read_next
                  end
@@ -49,12 +52,18 @@ class Expect
     private
 
     # 按声明组、会话、模式的顺序寻找首个匹配，不按文本中的出现位置重新排序。
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮快照须在同一次扫描保持一致。
     def find_match
-      @patterns.groups.each do |sessions, patterns|
+      # 单组且来源不重复时无需缓存；重复来源才为本轮扫描建立快照表。
+      groups = @patterns.groups
+      if groups.size > 1 || (groups.first && groups.first.first.size > @sessions.size)
+        snapshots = {}.compare_by_identity
+      end
+      groups.each do |sessions, patterns|
         sessions.each do |session|
           next if @handled_eof.include?(session)
 
-          buffer = session.buffer
+          buffer = snapshots ? (snapshots[session] ||= session.buffer) : session.buffer
           stalled = @stalled_matches[session]
           if stalled && stalled[:buffer] != buffer
             @stalled_matches.delete(session)
@@ -70,6 +79,7 @@ class Expect
       end
       nil
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
@@ -102,7 +112,12 @@ class Expect
       return result unless actions.any? { |action| continuing?(action) }
 
       @deadline = next_deadline if actions.include?(CONTINUE)
-      @sessions.all? { |candidate| @handled_eof.include?(candidate) } ? result : :retry
+      return result if @sessions.all? { |candidate| @handled_eof.include?(candidate) }
+
+      # 期限已过时不再扫描文本，但先派发已知 EOF；最后一个源结束不能被误报为超时。
+      @expired_eof_continuation = !actions.include?(CONTINUE) && expired?
+
+      :retry
     end
 
     # 在剩余期限内等待可读 IO；零超时仍允许首次非阻塞轮询，EINTR 重试不重新计时。
@@ -126,8 +141,13 @@ class Expect
 
     # 每个就绪 IO 读取一次，将异常归属到对应会话；仅显式启用时按接收数据刷新期限。
     def read_ready(readable, sessions)
+      # select 返回 IO 对象本身；共享同一 IO 时仍选择声明顺序中的首个会话。
+      if readable.size > 1
+        by_io = {}.compare_by_identity
+        sessions.each { |session| by_io[session.to_io] ||= session }
+      end
       readable.each do |io|
-        session = sessions.find { |candidate| candidate.to_io.equal?(io) }
+        session = by_io ? by_io.fetch(io) : sessions.find { |candidate| candidate.to_io.equal?(io) }
         begin
           # 转接回调消费匹配内容，余下字节交回 Relay，不能在这里提前转发两次。
           data = session.__send__(:read_available, propagate: !@relay_buffers.key?(session))
@@ -170,6 +190,7 @@ class Expect
 
       @deadline = next_deadline
       @polled = false
+      @expired_eof_continuation = false
       :retry
     end
   end

data/lib/expect/pattern.rb

@@ -18,8 +18,12 @@ class Expect
         offset = buffer.index(value)
         return [offset, value.bytesize, []] if offset
       when Regexp
-        text = buffer.dup
-        text.force_encoding(value.encoding) if value.fixed_encoding?
+        # 正则只读取输入；只有编码标记不同才复制，避免每个模式额外分配缓冲对象。
+        text = if value.fixed_encoding? && value.encoding != buffer.encoding
+                 buffer.dup.force_encoding(value.encoding)
+               else
+                 buffer
+               end
         unless text.valid_encoding?
           # 不完整的尾字符可能改变锚点或前瞻结果，必须等字符收齐后再匹配。
           validate_incomplete_suffix!(text, final: final)
@@ -28,9 +32,9 @@ class Expect
         found = value.match(text)
         return unless found
 
-        # Ruby 正则偏移按字符计算，缓冲切片按字节计算，必须转换；捕获组也统一返回字节串。
-        offset = text[0...found.begin(0)].bytesize
-        return [offset, found[0].bytesize, found.captures.map { |capture| capture&.b }]
+        # 直接使用正则的字节范围，避免为转换字符偏移创建前缀切片；捕获组也返回字节串。
+        offset, finish = found.byteoffset(0)
+        return [offset, finish - offset, found.captures.map { |capture| capture&.b }]
       end
       nil
     end

data/lib/expect/relay.rb

@@ -12,6 +12,7 @@ class Expect
       @previous = @sessions.to_h { |session| [session, session.__send__(:interaction_buffer)] }
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 共享读写循环统一维护来源和目标期限。
     def run
       @sessions.each { |session| session.__send__(:interaction_buffer=, @buffers.fetch(session)) }
       outputs.each(&:restart_timeout)
@@ -66,7 +67,7 @@ class Expect
 
               begin
                 if @buffers.key?(session)
-                  session.__send__(:read_available, propagate: false, buffer: @buffers.fetch(session))
+                  session.__send__(:read_available, propagate: false, buffer: @buffers.fetch(session), trim: false)
                 else
                   session.__send__(:read_available, propagate: false)
                 end
@@ -87,6 +88,7 @@ class Expect
       @previous.each { |session, buffer| session.__send__(:interaction_buffer=, buffer) }
       @buffers.each { |session, buffer| session.__send__(:restore_relay_buffer, buffer) }
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     private
 

data/lib/expect/relay_writer.rb

@@ -27,6 +27,7 @@ class Expect
     def done? = @offset == @data.bytesize && @flushed
 
     # 每轮每目标至多一次写入；真实 IO 永不在此等待，交给 Relay 的共同 select。
+    # 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?
@@ -54,6 +55,7 @@ class Expect
       check_timeout! if check_timeout
       true
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     def check_timeout!
       return unless deadline && Expect.monotonic >= deadline

data/lib/expect/session_resources.rb

@@ -19,8 +19,14 @@ class Expect
     def close_handles
       return unless own
 
-      # PTY 的读写端可能是同一个对象，先去重，重复关闭也保持安全。
-      [reader, writer, slave].compact.uniq.each { |io| io.close unless io.closed? }
+      # 初始化校验失败时可能含无效参数，只关闭真实 IO；PTY 读写端也需要去重。
+      failure = nil
+      [reader, writer, slave].grep(IO).uniq.each do |io|
+        io.close unless io.closed?
+      rescue IOError, SystemCallError => error
+        failure ||= error
+      end
+      raise failure if failure
     end
 
     # 非阻塞回收直属子进程，缓存 Process::Status，成功后清空 PID 以支持重复查询。
@@ -42,15 +48,27 @@ class Expect
     def finalize
       return unless owner == Process.pid
 
-      close_handles
-      owned_log.close if owned_log && !owned_log.closed?
-      reap
-      return unless pid
-
-      Process.kill("KILL", pid)
-      # 将最终 wait 交给后台回收线程，避免在 GC 终结器中阻塞等待。
-      Process.detach(pid)
-      @pid = nil
+      begin
+        close_handles
+      ensure
+        begin
+          owned_log.close if owned_log && !owned_log.closed?
+        ensure
+          # 每个阶段独立收尾；句柄或日志关闭失败不能跳过进程回收。
+          reap
+          if pid
+            begin
+              Process.kill("KILL", pid)
+            rescue Errno::ESRCH
+              # 子进程可能刚好退出，仍需尝试 wait，不能留下僵尸进程。
+              nil
+            end
+            # 将最终 wait 交给后台回收线程，避免在 GC 终结器中阻塞等待。
+            Process.detach(pid)
+            @pid = nil
+          end
+        end
+      end
     rescue IOError, SystemCallError
       nil
     end

data/lib/expect/terminal.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+# 会话终端的模式和窗口尺寸接口；人工接管期间的临时恢复由 interaction.rb 负责。
+class Expect
+  # 查询可恢复的终端模式字符串，或通过系统 stty 设置模式；参数按数组传递，不经 shell。
+  def stty(*modes)
+    return "" unless tty?
+
+    modes = modes.flat_map { |mode| Shellwords.split(mode.to_s) }
+    modes = ["-g"] if modes.empty?
+    reader, sink = IO.pipe
+    child = Process.spawn("stty", *modes, in: to_io, out: sink, err: sink)
+    sink.close
+    output = reader.read
+    _, status = Process.waitpid2(child)
+    raise IOError, "stty failed: #{output.strip}" unless status.success?
+
+    output.strip
+  rescue Errno::ENOENT
+    raise IOError, "stty executable not found in PATH; install the system terminal utilities"
+  ensure
+    reader&.close unless reader&.closed?
+    sink&.close unless sink&.closed?
+  end
+
+  # 读取终端的 [行数, 列数]。
+  def winsize = to_io.winsize
+
+  # 更新终端尺寸，由内核通知前台进程。
+  def winsize=(size)
+    to_io.winsize = size
+  end
+end

data/lib/expect/version.rb

@@ -2,5 +2,5 @@
 
 class Expect
   # Gem 与库共用的版本号；独立文件使 gemspec 无需加载完整会话实现。
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 end