expect-pty 0.8.3 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d2dcd5a8b2bbfcce02c7cc9873fda4c6574158ffe82a607f6b608ee65a261bc
-  data.tar.gz: fbecdd112d168d10b05d5e14a87f733021469f5a6c42963562779ad97e5c9456
+  metadata.gz: b56d5e855684574710a2b3de08554ff517979a5ad8a96ff455780f55b5313b4a
+  data.tar.gz: 7f9b80ed4cbe5b0bc98bee0b1400941cecbfefe4229c23fedd9837ce8550d393
 SHA512:
-  metadata.gz: 8ca9bae4a304942c41d19c274cbbeff9dacdb0c2d966d13e57a3c7dc8fbe4d81b4130c900d8e4e26f48600e7410e60d3677c206163b7bec88b7f474a49afe17f
-  data.tar.gz: 680b2db6dfbb16f4646f8e102c4607cda2d1e3781c7ab675fcde2234a3ad60d9f8edde425afcfc6c1aaa6c7d57eca5dab03033a884ed66ca7922f4b702d9f5c8
+  metadata.gz: ff9e7769c5ecfd1b4d6df2e6405b37acb9c8bcf5edbc5b0fbeea570bd50c774b1020a53d4593fb344efdd2404b8de0cce03f14c503011ab8079ac1649e4234be
+  data.tar.gz: 40d52a9b7388f2c740842b3c6abcd4c1d04787b4cf1c1ed20d7e855113e9d333330820f1404475a91698f9870426da2d85aeece9b728ed989b4628d3ef00b965

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.9.1 - 2026-10-18
+
+- 修复自定义 Numeric 转换失败时泄漏常规异常的问题；时间参数统一抛出 ArgumentError 并保留 cause，Interrupt/SystemExit 仍原样传播。
+
+## 0.9.0 - 2026-10-18
+
+- **不兼容**：命令默认直接按 argv 执行，单字符串也只作为可执行文件名，需要 shell 语法时须显式传入 `shell: true`。
+- **不兼容**：移除与标准库同名的加载入口，本库统一使用 `require "expect/pty"`，`require "expect"` 恢复加载标准库的 IO#expect。
+- **不兼容**：时间参数只接受有限实数 Numeric 或 nil，不再解析字符串，非法值统一抛出 ArgumentError。
+- 新增每次等待的 `search_window` 字节窗口选项，限制长输出中的字符串和正则扫描范围，匹配结果仍保留完整缓冲偏移。
+- 启动失败保留 `SpawnError#errno` 和 SystemCallError cause，包含非法编码字节的路径也能正确报告失败。
+- 缩短已退出子进程的关闭等待，并减少未启用日志时的匹配分配。
+- 修复正则转接在小缓冲窗口下丢失 UTF-8 字符前缀的问题，合法分片可跨超时继续匹配，EOF 时仍拒绝未完成字符。
+
 ## 0.8.3 - 2026-10-17
 
 - 修复多参数写入和日志补记受 Ruby 全局分隔符 `$,` 影响而插入额外字节的问题，保持原始字节和写入计数准确。

data/README.md

@@ -34,7 +34,7 @@ Expect.spawn("ruby", "-e", program) do |session|
 end
 ~~~
 
-The block closes the session and reaps its child process, including when the block raises. Use separate command arguments for untrusted input; a single command string follows Ruby shell semantics.
+The block closes the session and reaps its child process, including when the block raises. Commands execute directly with separate argv entries, including a single executable string. Shell syntax requires explicit `shell: true` with one command string; never pass untrusted input into that string.
 
 ## Features
 

data/README.zh-CN.md

@@ -34,7 +34,7 @@ Expect.spawn("ruby", "-e", program) do |session|
 end
 ~~~
 
-代码块退出时会关闭会话并回收子进程，异常路径也会执行清理。不可信命令参数应分别传入；单个命令字符串遵循 Ruby shell 语义。
+代码块退出时会关闭会话并回收子进程，异常路径也会执行清理。命令默认直接执行，单字符串也仅作为可执行文件名；需要 shell 语法时显式传入 `shell: true`，且只能传一个命令字符串，不要将外部输入拼入该字符串。
 
 ## 功能
 

data/docs/API.md

@@ -5,13 +5,16 @@
 
 ## 创建与关闭
 
-`Expect.spawn(*command, env: {}, chdir: nil, raw: false, graceful: false, **settings)` 创建并启动 PTY。
+`Expect.spawn(*command, env: {}, chdir: nil, raw: false, shell: false, graceful: false, **settings)` 创建并启动 PTY。
 `settings` 是下文列出的六个显式会话关键字的统称，并非任意配置 Hash。需要预设终端时先 `Expect::Session.new(**settings)`，
-通过 `session.slave` 使用原生终端方法，再调用 `session.spawn(*command, env: {}, chdir: nil, raw: false)`。
+通过 `session.slave` 使用原生终端方法，再调用 `session.spawn(*command, env: {}, chdir: nil, raw: false, shell: false)`。
 Session 构造器不接收命令或操作参数。同一会话只能启动一次。
 
-单字符串遵循 Ruby 的自动 shell 语义；多个独立参数按 argv 执行。外部输入应作为独立参数传入。
-启动失败抛出 `Expect::SpawnError`；工厂失败时回收尚未交付的会话。
+命令默认直接按可执行文件名与 argv 执行，单字符串也只作为文件名。需要 shell 语法时显式指定
+`shell: true`，仅接受一个字符串并交给 `/bin/sh -c`；外部输入应作为独立 argv 传入。
+启动失败抛出 `Expect::SpawnError`；系统错误的 `errno` 和 `cause` 保存错误编号与相应 `SystemCallError`。
+通过 `error.cause.is_a?(Errno::ENOENT)` 判断原因，外层仍为 SpawnError。非系统错误保留描述，不按任意类名恢复异常。
+工厂失败时回收尚未交付的会话。
 
 `Expect.open(io, writer: io, own: false, graceful: false, **settings)` 适配真实可 select 的 IO，默认借用。
 `own: true` 接管关闭责任，包括初始化中已知设置的非法值导致的失败；未知关键字在 Ruby 方法入口拒绝，此时不接管 IO。
@@ -28,7 +31,7 @@ nil。
 
 ## 匹配与回调
 
-`session.expect(*patterns, timeout: session.timeout, deadline: nil, consume: true, reset_timeout_on_read: false)` 返回不可变
+`session.expect(*patterns, timeout: session.timeout, deadline: nil, consume: true, reset_timeout_on_read: false, search_window: nil)` 返回不可变
 `Expect::Result`。
 `Expect.expect` 使用相同操作关键字，另加 `from:` 指定默认来源；其 timeout 默认 nil。模式为 String、Regexp、`:eof` 或
 `:timeout`，
@@ -55,6 +58,13 @@ result => { number:, captures: }
 `reset_timeout_on_read: true` 使每次读取重置本轮相对期限。`deadline` 是单调时钟绝对秒数，不被输入或回调延长。
 IO 期限不打断用户代码或单次正则；不可信正则应使用 Ruby `Regexp` 自身的 timeout。
 
+`search_window` 为正 Integer 字节数或 nil，只作用于本次等待，包括 Responder 的完成模式与应答规则。
+nil 保留全缓冲扫描；指定时，字符串和正则只搜索最新的尾部窗口。它不限制接收缓冲内存，也不丢弃旧字节，
+结果的 before/after 和消费范围仍相对于完整缓冲。长输出建议同时按业务需要设置 `buffer_limit` 并用 transcript 保存全文。
+窗口必须容纳完整提示与跨读取片段，窗口之外的模式可能错过；正则的锚点、前瞻和后顾只看到独立窗口。
+固定 UTF-8 正则跳过边界切开的合法首字符，等待合法未完成尾字符；窗口内非法字节及 EOF 未完成字符仍报错。
+二进制正则按原始字节匹配。
+
 Result 字段为 `number`、`error`、`match`、`before`、`after`、`session`、`captures`。对象、文本及捕获数组均不可变，未参与捕获为
 nil。
 错误为 nil、`:timeout`、`:eof` 或原始 IO 异常；来源会话与异常不复制、不冻结。使用 `matched?`、`timeout?`、`eof?` 查询，
@@ -89,7 +99,7 @@ end
   静态字符串复制并冻结，块收到带 `before`、`match`、`captures` 的 Session；块返回值忽略，应答后继续等待。
 - `reply` 原样发送，行确认自行包含 `\n` 或 `\r`，分页可发送空格；空回复合法但不产生字节。
   不内置通用“全部确认”规则，调用方应按目标设备及业务选择精确提示和回复。
-- `expect(session, *patterns, timeout: session.timeout, deadline: nil)` 仅处理一个 Session；也可使用与 `expect` 相同的
+- `expect(session, *patterns, timeout: session.timeout, deadline: nil, search_window: nil)` 仅处理一个 Session；也可使用与 `expect` 相同的
   PatternList 块声明完成模式、EOF 和 timeout 回调。位置参数模式与块不能同时提供。
 - 自动应答与完成模式按最早的字节位置处理；同位置时完成模式先于应答，多个应答按声明顺序。
   不按正则长度推测未完成提示，不在未知提示上猜测回复。仅将成功匹配的文本视为完成，业务错误输出需由调用方注册为终止模式并检查。
@@ -122,6 +132,7 @@ end
 操作参数 `raw`、`consume`、`reset_timeout_on_read`、`graceful` 不持久化为会话设置。
 `buffer` 返回副本，`buffer=` 复制并应用上限，`clear_buffer` 移交并清空缓冲；`buffer_discarded_bytes` 累计窗口裁剪量，匹配消费不计入。
 显式替换/清空、实际裁剪和消费输入会清除正则转义历史；非消费匹配、未裁剪的等待与内部缓冲交接保持连续历史。
+正则转接历史默认保留至多 65,536 字节，设置 `buffer_limit` 后采用该上限。存在固定 UTF-8 正则时，历史预算至少为 3 字节，以保留四字节字符尚未接收完整的前缀；这不扩大普通匹配缓冲的上限，也不延迟协议转发。
 
 `write(*objects)` 按 to_s 写字节并返回字节数，`<<` 返回 Session，`puts` 遵循 Ruby IO 换行与数组规则并返回 nil。
 `send_slow(*objects, delay:)` 按字符延迟发送并收取回复。背压超时抛出 `Expect::WriteTimeout`，`bytes_written` 仅标识本次调用已确认进度，
@@ -165,5 +176,7 @@ outputs、转义和本地终端模式。
 `raw: false` 将终端设置留给调用方。transcript、logger 及自定义 writer 同步执行，应及时返回。
 
 `Expect.monotonic` 读取单调时钟，`Expect.duration` 校验秒数，`Expect.readable_sessions(*sources, timeout: 0)` 返回就绪来源。
+时间参数只接受有限实数 Numeric 或 nil，拒绝字符串、Complex、布尔值及非有限数，非法值统一抛 ArgumentError。
+相对期限必须非负，deadline 允许负数表示已到期。
 Matcher、Relay、资源账本和标为 `@api private` 的 Session 协作方法不是用户契约。RBS 覆盖公开声明；`rbs validate` 不验证 Ruby
 方法体。

data/docs/MIGRATION.md

@@ -1,5 +1,17 @@
 # 迁移说明
 
+## 0.8.x → 0.9.0：启动与时间参数
+
+- 始终使用 `require "expect/pty"`，Gemfile 指定 `require: "expect/pty"`。本库删除 `lib/expect.rb` 后，
+  `require "expect"` 恢复加载标准库的 IO#expect；两者可按任意顺序加载。
+- `Expect.spawn("echo A; echo B")` 改为 `Expect.spawn("echo A; echo B", shell: true)`；
+  常规命令优先拆成 `Expect.spawn("echo", argument)`。单字符串默认只查找同名可执行文件，含空格的路径无需 shell 转义。
+- timeout、write_timeout、delay、deadline 等秒数不再接受字符串；在应用输入边界明确解析后传入 Numeric。
+  nil 仍表示无期限，相对秒数须非负，deadline 允许已过期的负数，非法值统一为 ArgumentError。
+- 启动错误仍 rescue `Expect::SpawnError`，通过 `errno` 或 `cause` 判断系统原因。
+  错误消息中不可编码字节替换为 Unicode 替代字符，原始 errno 保留。
+- `search_window:` 是可选的每次等待参数，默认 nil 保持全缓冲扫描；与 buffer_limit 的区别见 API。
+
 ## 0.6.x → 0.7.0
 
 0.7.0 主动移除门面和旧配置接口，不提供兼容别名。最低版本仍为 Ruby 3.4，`require "expect/pty"` 和不可变 Result 保持不变。
@@ -65,4 +77,4 @@ end
 - 模式进入匹配器后冻结，运行中不能追加或替换本轮规则。
 - Gem 仅携带源码、RBS 与使用文档；测试、示例、基准和发布脚本从仓库取得。
 - 0.6.0 曾保留外层 Expect 门面和布尔配置，这两部分已由 0.7.0 的 Session 与操作关键字替代。
-- 单字符串命令保留 Ruby 自动 shell 语义；多参数命令按 argv 传入。
+- 0.7.0 当时保留单字符串自动 shell 语义；0.9.0 的变更见上文。

data/lib/expect/child_process.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Expect
+  # 启动与监管直属子进程；资源身份只保存在传入的 ResourceOwner，不持有 Session。
+  # @api private
+  class ChildProcess
+    def initialize(resources)
+      @resources = resources
+    end
+
+    def pid = @resources.pid
+
+    # 状态未知或 EINTR 时不伪造退出事实；等待循环继续使用原期限。
+    def status
+      @resources.reap
+    rescue Errno::EINTR
+      @resources.status
+    end
+
+    # 管道、fork 与 PID 登记维持原所有权窗口；可由 Session 提供子进程启动钩子。
+    def spawn(command, env:, chdir:, shell:)
+      from_child = to_parent = nil
+      Cleanup.always(-> { ResourceOwner.close_handles(from_child, to_parent) }) do
+        Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
+        to_parent.close_on_exec = true
+        child = Thread.handle_interrupt(Object => :never) do
+          @resources.pid = fork do
+            Thread.handle_interrupt(Object => :immediate) do
+              if block_given?
+                yield from_child, to_parent
+              else
+                exec_child(command, env:, chdir:, from_child:, to_parent:, shell:)
+              end
+            end
+          end
+        end
+        to_parent.close
+        @resources.slave.close
+        failure = from_child.read
+        raise_spawn_error(failure) unless failure.empty?
+        child
+      end
+    end
+
+    # 每阶段只计算一次期限；回收或信号被中断后仍沿用剩余预算，零预算也先做一次尝试。
+    def wait(period, signal: nil)
+      deadline = period && (Expect.monotonic + period)
+      interval = 0.001
+      loop do
+        state = status
+        return state if state || !pid || @resources.owner != Process.pid
+
+        begin
+          self.signal(signal) if signal
+          signal = nil
+        rescue Errno::EINTR
+          # 下轮先回收再重试信号，避免在无限等待或持续中断时忙等。
+          nil
+        end
+        # ESRCH 后可能已完成回收；即使预算耗尽，也要返回刚获得的状态。
+        return status unless pid
+
+        remaining = deadline && (deadline - Expect.monotonic)
+        return nil if remaining && remaining <= 0
+
+        pause = remaining ? [interval, remaining].min : interval
+        block_given? ? yield(pause) : sleep(pause)
+        interval = [interval * 2, 0.01].min
+      end
+    end
+
+    # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。
+    def signal(signal)
+      return unless pid && @resources.owner == Process.pid
+
+      Process.kill(signal, pid)
+    rescue Errno::ESRCH
+      @resources.reap
+    end
+
+    # 子进程独占控制终端；成功 exec 关闭错误管道，失败时回传后立即退出。
+    def exec_child(command, env:, chdir:, from_child:, to_parent:, shell:)
+      from_child.close
+      Process.setsid
+      # 创建独立进程会话后重新打开 slave，使它成为子进程的控制终端。
+      File.open(@resources.slave.path, File::RDWR) do |terminal|
+        # 重定向操作系统的标准描述符；即使宿主替换过 Ruby 标准流，也能正确连接子进程。
+        # rubocop:disable Style/GlobalStdStream
+        STDIN.reopen(terminal)
+        STDOUT.reopen(terminal)
+        STDERR.reopen(terminal)
+        # rubocop:enable Style/GlobalStdStream
+      end
+      @resources.close_handles
+      Dir.chdir(chdir) if chdir
+      executable, *arguments = shell ? ["/bin/sh", "-c", command.first] : command
+      exec(env, [executable, executable], *arguments, close_others: true)
+    rescue Exception => error # rubocop:disable Lint/RescueException -- 子进程回传启动异常后立即退出。
+      begin
+        message = error.message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        to_parent.write(JSON.generate(class: error.class.name, message:,
+                                      errno: error.is_a?(SystemCallError) ? error.errno : nil))
+      ensure
+        exit! 127
+      end
+    end
+
+    # 错误管道只传递标量；系统错误从 errno 恢复，不动态加载异常类。
+    def raise_spawn_error(payload)
+      failure = JSON.parse(payload)
+      errno = failure.fetch("errno")
+      message = "#{failure.fetch("class")}: #{failure.fetch("message")}"
+      cause = errno ? SystemCallError.new(failure.fetch("message"), errno) : ChildFailure.new(message)
+      raise SpawnError.new(message, errno:), cause:
+    rescue JSON::ParserError, KeyError => error
+      raise SpawnError.new("invalid child startup failure"), cause: error
+    end
+  end
+  private_constant :ChildProcess
+end

data/lib/expect/interaction.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "relay_writer"
+require_relative "relay/writer"
 require_relative "relay"
 require_relative "literal_prefix"
 
@@ -188,6 +188,8 @@ module Expect
     # 已转发历史有界保留，固定 UTF-8 正则不能从续字节开始匹配。
     def self.trim_history(history, data, limit:, utf8:)
       history << data
+      # 四字节 UTF-8 字符在下一片到来前最多需要保留三个字节；小窗口不能截掉这段编码状态。
+      limit = [limit, 3].max if utf8
       return unless history.bytesize > limit
 
       history.replace(history.byteslice(-limit, limit))
@@ -204,15 +206,13 @@ module Expect
     def queue_output(data)
       @pending_writes = @outputs.map do |target|
         if target.is_a?(InteractOutput)
-          RelayWriter.new(target.target, target.render(data))
+          Relay::Writer.new(target.target, target.render(data))
         else
-          RelayWriter.new(target, data)
+          Relay::Writer.new(target, data)
         end
       end
     end
 
-    public
-
     # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
     # @api private
     attr_reader :sequences

data/lib/expect/logging.rb

@@ -130,8 +130,11 @@ module Expect
     end
 
     # 向标准 Logger 提交不可变事件，不包含会话对象；格式化由 logger 完成。
-    def trace(message, severity: Logger::INFO, event: :matched)
-      logger&.add(severity, { event:, pid:, fd: fileno, message: message.freeze }.freeze, "Expect")
+    def trace(message = nil, severity: Logger::INFO, event: :matched)
+      return unless logger
+
+      message = yield if block_given?
+      logger.add(severity, { event:, pid:, fd: fileno, message: message.freeze }.freeze, "Expect")
     end
 
     # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。

data/lib/expect/matcher.rb

@@ -7,12 +7,13 @@ module Expect
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
     def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false,
-                   match_by_position: false)
+                   match_by_position: false, search_window: nil)
       @patterns = patterns.finalize!
       @sessions = patterns.sessions
       @groups = patterns.text_groups
       @consume = consume
       @match_by_position = match_by_position
+      @search_window = search_window
       @reset_timeout_on_read = reset_timeout_on_read
       @timeout = Expect.duration(timeout)
       # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
@@ -97,7 +98,9 @@ module Expect
             return nil if hard_expired?
             next if stalled && stalled[:patterns].key?(pattern)
 
-            position = if pattern.value.is_a?(String)
+            position = if @search_window
+                         pattern.locate(buffer, final: session.eof?, search_window: @search_window)
+                       elsif pattern.value.is_a?(String)
                          locate_literal(session, pattern, buffer)
                        else
                          pattern.locate(buffer, final: session.eof?)
@@ -277,4 +280,5 @@ module Expect
       :retry
     end
   end
+  private_constant :Matcher
 end

data/lib/expect/pattern.rb

@@ -21,7 +21,9 @@ module Expect
     # buffer 应为二进制字符串，offset 仅用于字面扫描；正则始终看到完整窗口以保留锚点语义。
     # captures 为 false 时只求字节范围，转义扫描不分配随后丢弃的捕获字符串。
     # final 表示不会再有新输入，此时不完整的编码尾部也必须报错，不能永远当作等待分片。
-    def locate(buffer, final: false, offset: 0, captures: true)
+    def locate(buffer, final: false, offset: 0, captures: true, search_window: nil)
+      return locate_window(buffer, search_window, final:, captures:) if search_window && buffer.bytesize > search_window
+
       case value
       when String
         offset = buffer.index(value, offset)
@@ -50,6 +52,37 @@ module Expect
 
     private
 
+    # 显式尾部窗口单独匹配，返回偏移仍属于原始缓冲；字节协议不做转码。
+    def locate_window(buffer, size, final:, captures:)
+      start = buffer.bytesize - size
+      start = utf8_window_start(buffer, start, final:) if value.is_a?(Regexp) && value.fixed_encoding? &&
+                                                          value.encoding == Encoding::UTF_8
+      return nil unless start
+
+      # byteslice 会与完整缓冲共享存储，使下次追加复制整段；unpack 只复制本轮尾窗。
+      position = locate(buffer.unpack1("a*", offset: start), final:, captures:)
+      position[0] += start if position
+      position
+    end
+
+    # 只跳过被窗口边界切开的合法 UTF-8 字符，不隐藏窗口内的非法字节。
+    def utf8_window_start(buffer, start, final:)
+      lead = start
+      lead -= 1 while lead.positive? && start - lead < 3 && (buffer.getbyte(lead) & 0xc0) == 0x80
+      first = buffer.getbyte(lead)
+      width = if first.between?(0xc2, 0xdf) then 2
+              elsif first.between?(0xe0, 0xef) then 3
+              elsif first.between?(0xf0, 0xf4) then 4
+              else 1
+              end
+      character = buffer.byteslice(lead, width).dup.force_encoding(Encoding::UTF_8)
+      return start unless lead < start && lead + width > start
+      return lead + width if character.valid_encoding?
+
+      validate_incomplete_suffix!(character, final:)
+      nil
+    end
+
     # 仅容忍末尾尚未收全的 UTF-8 字符，其他非法编码直接报错，不静默替换接收字节。
     # 转码仅用于区分“不完整尾部”和“非法字节”，结果不回写缓冲，也不做编码归一化。
     def validate_incomplete_suffix!(text, final:)

data/lib/expect/pty.rb

@@ -1,4 +1,209 @@
 # frozen_string_literal: true
 
-# 提供明确的 Gem 加载入口，避免与 Ruby 标准库 expect.rb（IO#expect 扩展）同名冲突。
-require_relative "../expect"
+require "pty"
+require "json"
+require "io/console"
+require "stringio"
+require_relative "version"
+require_relative "result"
+require_relative "resource_owner"
+require_relative "pattern"
+require_relative "pattern_list"
+require_relative "matcher"
+require_relative "cleanup"
+require_relative "child_process"
+require_relative "session"
+require_relative "session_factory"
+require_relative "responder"
+
+# PTY 会话的创建、匹配与转接入口；可变状态只属于返回的 Session。
+module Expect
+  # 重置相对期限后继续等待。
+  CONTINUE = :continue
+  # 保留原相对期限继续等待。
+  CONTINUE_WITHOUT_RESET = :continue_without_reset
+  # 单轮非阻塞读写的最大字节数。
+  # @api private
+  READ_SIZE = 16_384
+  private_constant :READ_SIZE
+
+  # PTY 创建后命令启动失败。
+  class SpawnError < StandardError
+    # 子进程报告的系统错误编号；非系统启动错误为 nil。
+    attr_reader :errno
+
+    # 保持启动异常类型，并携带可用于诊断的系统错误编号。
+    def initialize(message = "process spawn failed", errno: nil)
+      @errno = errno
+      super(message)
+    end
+  end
+
+  # 未知子进程异常仅保留描述，不根据外部类名恢复对象。
+  # @api private
+  class ChildFailure < StandardError; end
+  private_constant :ChildFailure
+
+  # 拒绝同源递归转接及接收交付回调中的同源递归读取，防止数据归属和顺序被破坏。
+  class ReentrancyError < StandardError; end
+
+  # 本次写入已经确认交付的进度；其他嵌套写入的异常保留在 cause。
+  class WriteTimeout < IOError
+    # 本次 write 已被底层接受的字节数。
+    attr_reader :bytes_written
+
+    # 构造包含已交付字节数的背压超时。
+    def initialize(message = "write timed out", bytes_written: 0)
+      @bytes_written = bytes_written
+      super(message)
+    end
+  end
+
+  class << self
+    # 创建并启动 Session；有块时返回块结果，并按 graceful 策略关闭所属资源。
+    # raw 只控制本次子进程 PTY；日志与输出对象始终借用。
+    def spawn(*command, env: {}, chdir: nil, raw: false, shell: false, graceful: false,
+              timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
+      session = nil
+      spawned = false
+      cleanup = lambda do
+        if session && (block_given? || !spawned)
+          session.cleanup_session(nil, writer: nil, own: false, graceful: spawned && graceful)
+        end
+      end
+      Cleanup.always(cleanup) do
+        # 工厂在构造期间处理失败；成功对象的返回与登记不可被中断拆开。
+        Thread.handle_interrupt(Object => :never) do
+          session = SessionFactory.pty(timeout:, write_timeout:, buffer_limit:, logger:, transcript:, outputs:)
+        end
+        session.spawn(*command, env:, chdir:, raw:, shell:)
+        spawned = true
+        block_given? ? yield(session) : session
+      end
+    end
+
+    # 适配真实 IO；own 只决定读写端点的关闭责任，日志与输出目标仍由调用者管理。
+    # 有块时返回块结果；初始化失败也清理已取得的所属端点。
+    def open(io, writer: io, own: false, graceful: false,
+             timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
+      session = nil
+      initialized = false
+      constructing = false
+      cleanup = lambda do
+        if session && (block_given? || !initialized)
+          session.cleanup_session(io, writer:, own:, graceful: initialized && graceful)
+        elsif !session && own && !constructing
+          ResourceOwner.close_handles(io, writer)
+        end
+      end
+      Cleanup.always(cleanup) do
+        Thread.handle_interrupt(Object => :never) do
+          constructing = true
+          session = SessionFactory.io(io, writer:, own:, timeout:, write_timeout:, buffer_limit:,
+                                          logger:, transcript:, outputs:)
+        end
+        initialized = true
+        block_given? ? yield(session) : session
+      end
+    end
+
+    # 按 outputs 建立转发图，返回引发停止的 Session；总期限到达返回 nil。
+    def interconnect(*sessions, timeout: nil)
+      raise ArgumentError, "interconnect requires Session objects" unless sessions.any? && sessions.all?(Session)
+
+      Relay.new(sessions, timeout).run
+    end
+
+    # 共同等待指定来源，返回不可变 Result。consume 控制本轮是否消费匹配文本。
+    # reset_timeout_on_read 仅重置相对期限，deadline 始终是不可延长的总期限。
+    def expect(*patterns, from: [], timeout: nil, deadline: nil, consume: true, reset_timeout_on_read: false,
+               search_window: nil, &)
+      run_expect(from, patterns, timeout, deadline:, consume:, reset_timeout_on_read:, search_window:, &)
+    end
+
+    # 返回回调继续控制符，reset_timeout 为 false 时保留原相对期限。
+    def continue(reset_timeout: true) = reset_timeout ? CONTINUE : CONTINUE_WITHOUT_RESET
+
+    # 当前单调时钟秒数；供跨多次等待共享 deadline。
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # 转换有限非负秒数，nil 表示无相对期限。
+    def duration(value)
+      return nil if value.nil?
+
+      number = numeric_seconds(value)
+      raise ArgumentError, "duration must be finite and nonnegative" unless number >= 0
+
+      number
+    end
+
+    # 返回可读 Session，不消费输入；去重、排除已关闭来源，并保留声明顺序。
+    def readable_sessions(*sessions, timeout: 0)
+      timeout = duration(timeout)
+      raise ArgumentError, "readable_sessions requires Session objects" unless sessions.all?(Session)
+
+      active = sessions.uniq(&:object_id).reject(&:closed?)
+      return [] if active.empty?
+
+      deadline = timeout && (monotonic + timeout)
+      polled = false
+      ready = nil
+      loop do
+        remaining = deadline && [deadline - monotonic, 0].max
+        return [] if polled && remaining&.zero?
+
+        begin
+          ready = IO.select(active.map(&:to_io), nil, nil, remaining)
+          break
+        rescue Errno::EINTR
+          polled = true
+        end
+      end
+      return [] unless ready
+
+      select_ready_sessions(active, ready.first)
+    end
+
+    private
+
+    # 数值协议统一拒绝非实数和非有限值；不宽松解析字符串或布尔值。
+    def numeric_seconds(value)
+      raise ArgumentError, "seconds must be a real Numeric" unless value.is_a?(Numeric) && !value.is_a?(Complex)
+
+      number = begin
+        Float(value)
+      rescue StandardError
+        # Numeric 子类也可自定义转换；只归一化转换失败，保留致命中断和原始 cause。
+        raise ArgumentError, "seconds must be a finite real Numeric"
+      end
+      raise ArgumentError, "seconds must be finite" unless number.finite?
+
+      number
+    end
+
+    # 按对象身份归属就绪描述符，不能用 IO 的值相等规则合并来源。
+    def select_ready_sessions(sessions, readable)
+      by_io = readable.each_with_object({}.compare_by_identity) { |io, index| index[io] = true }
+      sessions.select { |session| by_io.key?(session.to_io) }
+    end
+
+    # 声明完成后固定模式；有参数块保留调用方 self，无参数块使用模式 DSL。
+    def run_expect(sessions, patterns, timeout, deadline:, consume:, reset_timeout_on_read:,
+                   match_by_position: false, search_window: nil, &block)
+      unless search_window.nil? || (search_window.is_a?(Integer) && search_window.positive?)
+        raise ArgumentError, "search_window must be a positive Integer or nil"
+      end
+
+      timeout = duration(timeout)
+      deadline = numeric_seconds(deadline) unless deadline.nil?
+      raise ArgumentError, "provide patterns or a pattern block, not both" if block_given? && !patterns.empty?
+
+      pattern_list = PatternList.new(sessions, patterns)
+      if block
+        block.parameters.empty? ? pattern_list.instance_exec(&block) : block.call(pattern_list)
+      end
+      Matcher.new(pattern_list, timeout, deadline:, consume:, reset_timeout_on_read:, match_by_position:,
+                                         search_window:).run
+    end
+  end
+end

data/lib/expect/relay/writer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Expect
+  class Relay
+    # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
+    # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
+    # @api private
+    class Writer
+      # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
+      attr_reader :target, :deadline
+
+      # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
+      def initialize(target, data)
+        @target = target
+        @data = data
+        @offset = 0
+        @flushed = false
+        restart_timeout
+      end
+
+      # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
+      # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
+      def restart_timeout
+        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?(Session)
+
+        target if target.is_a?(IO)
+      end
+
+      # 数据交付完但 flush 失败仍未完成；重试只补 flush，不重新发送已接受的数据。
+      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?(Session) && target.closed?
+
+        if @offset < @data.bytesize
+          bytes = @data.byteslice(@offset, READ_SIZE)
+          count = io ? io.write_nonblock(bytes, exception: false) : target.write(bytes)
+          if io && count == :wait_writable
+            check_timeout! if check_timeout
+            return false
+          end
+          unless count.is_a?(Integer) && count.positive? && count <= bytes.bytesize
+            raise IOError, "write must return the number of accepted bytes"
+          end
+
+          @offset += count
+          # 先登记底层已接受的进度，再通知诊断；logger 失败后恢复只补未发送后缀。
+          trace_delivery(bytes.byteslice(0, count)) if target.is_a?(Session)
+        end
+        if @offset == @data.bytesize
+          # write_nonblock 已直接写到底层；普通 write 对象仍遵守自身 flush 协议。
+          target.flush if !io && target.respond_to?(:flush)
+          @flushed = true
+        end
+        true
+      rescue Errno::EINTR
+        # 未获得写入计数就不移动游标；先检查原期限，再让共同循环轮询输入并重试。
+        check_timeout! if check_timeout
+        true
+      end
+
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # 保留本数据块已交付的进度，便于调用方区分未写入和部分写入；不清空恢复用的游标。
+      def check_timeout!
+        return unless deadline && Expect.monotonic >= deadline
+
+        raise WriteTimeout.new("relay target write timed out", bytes_written: @offset)
+      end
+
+      private
+
+      # 诊断可嵌套写入；外层只报告本游标的进度，原超时及其内层进度保留在 cause。
+      def trace_delivery(data)
+        target.__send__(:trace_data, :sending, data)
+      rescue WriteTimeout
+        raise WriteTimeout.new("relay interrupted by a diagnostic timeout", bytes_written: @offset)
+      end
+    end
+  end
+end

data/lib/expect/resource_owner.rb

@@ -108,4 +108,5 @@ module Expect
       @pid = nil
     end
   end
+  private_constant :ResourceOwner
 end

data/lib/expect/responder.rb

@@ -31,7 +31,8 @@ module Expect
     # 等待完成模式或 EOF，同时自动处理提示；timeout 沿用会话默认值，应答不重置期限。
     # 完成块使用 PatternList DSL；Result 只描述最后一次匹配，全文请用会话 transcript 保存。
     # 每次等待快照规则，回调修改规则仅影响后续等待；不接管或关闭会话。
-    def expect(session, *patterns, timeout: (session.timeout if session.is_a?(Session)), deadline: nil, &block)
+    def expect(session, *patterns, timeout: (session.timeout if session.is_a?(Session)), deadline: nil,
+               search_window: nil, &block)
       raise ArgumentError, "responder requires a Session" unless session.is_a?(Session)
 
       raise ArgumentError, "provide patterns or a pattern block, not both" if block && !patterns.empty?
@@ -39,7 +40,7 @@ module Expect
       rules = @rules.dup.freeze
       Expect.__send__(
         :run_expect, [session], [], timeout, deadline:, consume: true,
-                                             reset_timeout_on_read: false, match_by_position: true
+                                             reset_timeout_on_read: false, match_by_position: true, search_window:
       ) do |list|
         patterns.each do |pattern|
           case pattern

data/lib/expect/session.rb

@@ -48,34 +48,25 @@ module Expect
     end
 
     # 等待自身输入，返回 Result；匹配消费和接收重置策略只对本轮有效。
-    def expect(*patterns, timeout: self.timeout, deadline: nil, consume: true, reset_timeout_on_read: false, &)
-      Expect.__send__(:run_expect, [self], patterns, timeout, deadline:, consume:, reset_timeout_on_read:, &)
+    def expect(*patterns, timeout: self.timeout, deadline: nil, consume: true, reset_timeout_on_read: false,
+               search_window: nil, &)
+      Expect.__send__(:run_expect, [self], patterns, timeout,
+                      deadline:, consume:, reset_timeout_on_read:, search_window:, &)
     end
 
     # 在新控制终端中执行命令并同步确认 exec 结果；同一会话只能启动一次。
-    def spawn(*command, env: {}, chdir: nil, raw: false)
+    def spawn(*command, env: {}, chdir: nil, raw: false, shell: false)
       validate_spawn!(command)
+      raise ArgumentError, "shell must be true or false" unless [true, false].include?(shell)
+      raise ArgumentError, "shell requires one command string" if shell && command.size != 1
 
       @slave.raw! if raw
-      from_child = to_parent = nil
-      Cleanup.always(-> { ResourceOwner.close_handles(from_child, to_parent) }) do
-        # 错误管道的写端在 exec 成功时自动关闭；父进程据此区分成功启动与 exec 前失败。
-        # 管道返回到多重赋值之间也属于接管区间，确保 ensure 始终能找到两个端点。
-        Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
-        to_parent.close_on_exec = true
-        @command = command.map { |part| part.dup.freeze }.freeze
-        # 原生 fork 返回后先登记 PID，再交付线程中断或终止，避免清理时遗漏新子进程。
-        child = Thread.handle_interrupt(Object => :never) do
-          @resources.pid = fork do
-            # 子进程不继承父侧登记临界区，执行前仍可立即响应异步异常。
-            Thread.handle_interrupt(Object => :immediate) { exec_child(command, env:, chdir:, from_child:, to_parent:) }
-          end
+      @command = command.map { |part| part.dup.freeze }.freeze
+      Cleanup.on_failure(-> { hard_close }) do
+        child = @child_process.spawn(command, env:, chdir:, shell:) do |from_child, to_parent|
+          exec_child(command, env:, chdir:, from_child:, to_parent:, shell:)
         end
-        to_parent.close
-        @slave.close
-        failure = from_child.read
-        Cleanup.always(-> { hard_close }) { raise SpawnError, failure } unless failure.empty?
-        trace("spawned pid=#{child}", event: :spawned)
+        trace(event: :spawned) { "spawned pid=#{child}" }
         self
       end
     end
@@ -100,10 +91,7 @@ module Expect
 
     # 非阻塞回收并缓存子进程状态；未退出或仅适配 IO 时返回 nil。
     def process_status
-      @resources.reap
-    rescue Errno::EINTR
-      # 单次轮询被中断时状态仍未知；wait/close 会在原期限内继续，不在这里无限重试。
-      @resources.status
+      @child_process.status
     end
 
     # 已知进程退出码；尚未回收或信号退出时为 nil。
@@ -328,7 +316,7 @@ module Expect
       end
       # 诊断回调可能嵌套等待；恢复本次结果后再交给正式模式回调，不能返回内层等待的结果。
       result = @last_result
-      trace("matched pattern #{pattern.number}")
+      trace { "matched pattern #{pattern.number}" }
       @last_result = result
     end
 
@@ -400,6 +388,7 @@ module Expect
     def initialize_io(reader, writer:, slave: nil, own: false, timeout: nil, write_timeout: nil,
                       buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
       @resources = ResourceOwner.new(reader, writer:, slave:, own:)
+      @child_process = ChildProcess.new(@resources)
       raise ArgumentError, "reader must be a real IO" unless reader.is_a?(IO) && !reader.closed?
       raise ArgumentError, "writer must be a real IO" unless writer.is_a?(IO) && !writer.closed?
 
@@ -444,28 +433,9 @@ module Expect
       raise ArgumentError, "command is empty" if command.first.empty?
     end
 
-    # 子进程独占控制终端；成功 exec 关闭错误管道，失败时回传后立即退出。
-    def exec_child(command, env:, chdir:, from_child:, to_parent:)
-      from_child.close
-      Process.setsid
-      # 创建独立进程会话后重新打开 slave，使它成为子进程的控制终端。
-      File.open(@tty_name, File::RDWR) do |terminal|
-        # 重定向操作系统的标准描述符；即使宿主替换过 Ruby 标准流，也能正确连接子进程。
-        # rubocop:disable Style/GlobalStdStream
-        STDIN.reopen(terminal)
-        STDOUT.reopen(terminal)
-        STDERR.reopen(terminal)
-        # rubocop:enable Style/GlobalStdStream
-      end
-      @resources.close_handles
-      Dir.chdir(chdir) if chdir
-      exec(env, *command, close_others: true)
-    rescue Exception => error # rubocop:disable Lint/RescueException -- 子进程回传启动异常后立即退出。
-      begin
-        to_parent.write("#{error.class}: #{error.message}")
-      ensure
-        exit! 127
-      end
+    # 保留 Session 子类的启动钩子；进程对象管理控制终端和错误协议。
+    def exec_child(command, **)
+      @child_process.exec_child(command, **)
     end
 
     # EINTR 未确认交付时不移动游标；其他写入计数必须落在当前块范围内。
@@ -559,28 +529,9 @@ module Expect
       wait_for_child(1, signal: "KILL")
     end
 
-    # 每阶段只计算一次期限；回收或信号被中断后仍沿用剩余预算，零预算也先做一次尝试。
+    # Session 的 sleep 钩子保留给受控时钟；期限与信号状态属于进程对象。
     def wait_for_child(period, signal: nil)
-      deadline = period && (Expect.monotonic + period)
-      loop do
-        status = process_status
-        return status if status || !pid || @resources.owner != Process.pid
-
-        begin
-          signal_child(signal) if signal
-          signal = nil
-        rescue Errno::EINTR
-          # 下轮先回收再重试信号，避免在无限等待或持续中断时忙等。
-          nil
-        end
-        # ESRCH 后可能已完成回收；即使预算耗尽，也要返回刚获得的状态。
-        return process_status unless pid
-
-        remaining = deadline && (deadline - Expect.monotonic)
-        return nil if remaining && remaining <= 0
-
-        sleep(remaining ? [0.01, remaining].min : 0.01)
-      end
+      @child_process.wait(period, signal:) { |pause| sleep(pause) }
     end
 
     # 只结束读取方向并冲刷接收记录；EOF 不代表子进程已经退出或写端已经关闭。
@@ -603,14 +554,5 @@ module Expect
       # 丢弃的前缀使当前窗口与已转发历史之间不再连续。
       @relay_history.clear
     end
-
-    # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。
-    def signal_child(signal)
-      return unless pid && @resources.owner == Process.pid
-
-      Process.kill(signal, pid)
-    rescue Errno::ESRCH
-      @resources.reap
-    end
   end
 end

data/lib/expect/session_factory.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Expect
+  # 统一管理部分构造对象；调用方只在受保护的移交区间接收已初始化会话。
+  # @api private
+  module SessionFactory
+    def self.pty(**)
+      session = nil
+      Cleanup.on_failure(-> { session&.cleanup_session(nil, writer: nil, own: false) }) do
+        session = Session.allocate
+        Thread.handle_interrupt(Object => :immediate) { session.__send__(:initialize, **) }
+        session
+      end
+    end
+
+    def self.io(reader, writer:, own:, **)
+      session = nil
+      cleanup = lambda do
+        if session
+          session.cleanup_session(reader, writer:, own:)
+        elsif own
+          ResourceOwner.close_handles(reader, writer)
+        end
+      end
+      Cleanup.on_failure(cleanup) do
+        session = Session.allocate
+        Thread.handle_interrupt(Object => :immediate) do
+          session.__send__(:initialize_io, reader, writer:, own:, **)
+        end
+        session
+      end
+    end
+  end
+  private_constant :SessionFactory
+end

data/lib/expect/version.rb

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

data/sig/expect.rbs

@@ -1,6 +1,6 @@
 # 公开 Session 接口；内部匹配与转接协议在源码中标记为 @api private。
 module Expect
-  type duration = Numeric | String
+  type duration = Numeric
   type pattern = String | Regexp | :eof | :timeout
   type result_error = :eof | :timeout | Exception | nil
   type result_fields = { number: Integer?, error: result_error, match: String?, before: String?, after: String?, session: Session?, captures: Array[String?] }
@@ -21,6 +21,9 @@ module Expect
   CONTINUE_WITHOUT_RESET: :continue_without_reset
 
   class SpawnError < StandardError
+    attr_reader errno: Integer?
+
+    def initialize: (?String message, ?errno: Integer?) -> void
   end
 
   class ReentrancyError < StandardError
@@ -33,12 +36,12 @@ module Expect
   end
 
   def self.spawn: (
-      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?graceful: bool,
+      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool, ?graceful: bool,
       ?timeout: duration?, ?write_timeout: duration?, ?buffer_limit: Integer?,
       ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
     ) -> Session
     | [A] (
-      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?graceful: bool,
+      *String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool, ?graceful: bool,
       ?timeout: duration?, ?write_timeout: duration?, ?buffer_limit: Integer?,
       ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
     ) { (Session) -> A } -> A
@@ -66,7 +69,7 @@ module Expect
 
   def self.expect: (
       *pattern patterns, ?from: (Session | Array[Session]), ?timeout: duration?, ?deadline: duration?,
-      ?consume: bool, ?reset_timeout_on_read: bool
+      ?consume: bool, ?reset_timeout_on_read: bool, ?search_window: Integer?
     ) ?{ (PatternList) -> untyped } -> Result
 
   class Session
@@ -75,10 +78,10 @@ module Expect
         ?logger: _Logger?, ?transcript: _Writer?, ?outputs: Array[_Writer]
       ) -> void
 
-    def spawn: (*String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool) -> Session
+    def spawn: (*String command, ?env: Hash[String, String?], ?chdir: String?, ?raw: bool, ?shell: bool) -> Session
 
     def expect: (
-        *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?consume: bool, ?reset_timeout_on_read: bool
+        *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?consume: bool, ?reset_timeout_on_read: bool, ?search_window: Integer?
       ) ?{ (PatternList) -> untyped } -> Result
 
     def after: () -> String?
@@ -272,7 +275,7 @@ module Expect
     def on: ((String | Regexp) pattern, ?reply: String?, ?limit: Integer?)
       ?{ (Session) -> untyped } -> Responder
 
-    def expect: (Session session, *pattern patterns, ?timeout: duration?, ?deadline: duration?)
+    def expect: (Session session, *pattern patterns, ?timeout: duration?, ?deadline: duration?, ?search_window: Integer?)
       ?{ (PatternList) -> untyped } -> Result
 
     def inspect: () -> String

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.9.1
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -64,7 +78,7 @@ files:
 - docs/API.md
 - docs/COMPATIBILITY.md
 - docs/MIGRATION.md
-- lib/expect.rb
+- lib/expect/child_process.rb
 - lib/expect/cleanup.rb
 - lib/expect/interaction.rb
 - lib/expect/literal_prefix.rb
@@ -75,11 +89,12 @@ files:
 - lib/expect/pty.rb
 - lib/expect/redactor.rb
 - lib/expect/relay.rb
-- lib/expect/relay_writer.rb
+- lib/expect/relay/writer.rb
 - lib/expect/resource_owner.rb
 - lib/expect/responder.rb
 - lib/expect/result.rb
 - lib/expect/session.rb
+- lib/expect/session_factory.rb
 - lib/expect/version.rb
 - sig/expect.rbs
 homepage: https://github.com/gatework/expect-ruby

data/lib/expect/relay_writer.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Expect
-  # 向单个转接目标写入数据，维护发送进度与期限；恢复时不重放已成功写出的前缀。
-  # 只借用目标，不 dup 描述符，也不负责读取；所有就绪等待统一交给 Relay 调度。
-  # @api private
-  class RelayWriter
-    # target 始终借用；deadline 是本轮背压预算，不表示整块数据已交付。
-    attr_reader :target, :deadline
-
-    # data 在本游标存活期间由上层保持不变，offset 始终以实际交付的字节数计量。
-    def initialize(target, data)
-      @target = target
-      @data = data
-      @offset = 0
-      @flushed = false
-      restart_timeout
-    end
-
-    # 初次排队或重新进入 interconnect 时开始新的写入预算；普通短写不会刷新期限。
-    # 只有 Expect 目标提供 write_timeout，原生 IO 和自定义目标只受转接总期限约束。
-    def restart_timeout
-      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?(Session)
-
-      target if target.is_a?(IO)
-    end
-
-    # 数据交付完但 flush 失败仍未完成；重试只补 flush，不重新发送已接受的数据。
-    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?(Session) && target.closed?
-
-      if @offset < @data.bytesize
-        bytes = @data.byteslice(@offset, READ_SIZE)
-        count = io ? io.write_nonblock(bytes, exception: false) : target.write(bytes)
-        if io && count == :wait_writable
-          check_timeout! if check_timeout
-          return false
-        end
-        unless count.is_a?(Integer) && count.positive? && count <= bytes.bytesize
-          raise IOError, "write must return the number of accepted bytes"
-        end
-
-        @offset += count
-        # 先登记底层已接受的进度，再通知诊断；logger 失败后恢复只补未发送后缀。
-        trace_delivery(bytes.byteslice(0, count)) if target.is_a?(Session)
-      end
-      if @offset == @data.bytesize
-        # write_nonblock 已直接写到底层；普通 write 对象仍遵守自身 flush 协议。
-        target.flush if !io && target.respond_to?(:flush)
-        @flushed = true
-      end
-      true
-    rescue Errno::EINTR
-      # 未获得写入计数就不移动游标；先检查原期限，再让共同循环轮询输入并重试。
-      check_timeout! if check_timeout
-      true
-    end
-
-    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
-    # 保留本数据块已交付的进度，便于调用方区分未写入和部分写入；不清空恢复用的游标。
-    def check_timeout!
-      return unless deadline && Expect.monotonic >= deadline
-
-      raise WriteTimeout.new("relay target write timed out", bytes_written: @offset)
-    end
-
-    private
-
-    # 诊断可嵌套写入；外层只报告本游标的进度，原超时及其内层进度保留在 cause。
-    def trace_delivery(data)
-      target.__send__(:trace_data, :sending, data)
-    rescue WriteTimeout
-      raise WriteTimeout.new("relay interrupted by a diagnostic timeout", bytes_written: @offset)
-    end
-  end
-
-  private_constant :RelayWriter
-end

data/lib/expect.rb

@@ -1,167 +0,0 @@
-# frozen_string_literal: true
-
-require "pty"
-require "io/console"
-require "stringio"
-require_relative "expect/version"
-require_relative "expect/result"
-require_relative "expect/resource_owner"
-require_relative "expect/pattern"
-require_relative "expect/pattern_list"
-require_relative "expect/matcher"
-require_relative "expect/cleanup"
-require_relative "expect/session"
-require_relative "expect/responder"
-
-# PTY 会话的创建、匹配与转接入口；可变状态只属于返回的 Session。
-module Expect
-  # 重置相对期限后继续等待。
-  CONTINUE = :continue
-  # 保留原相对期限继续等待。
-  CONTINUE_WITHOUT_RESET = :continue_without_reset
-  # 单轮非阻塞读写的最大字节数。
-  # @api private
-  READ_SIZE = 16_384
-
-  # PTY 创建后命令启动失败。
-  class SpawnError < StandardError; end
-
-  # 拒绝同源递归转接及接收交付回调中的同源递归读取，防止数据归属和顺序被破坏。
-  class ReentrancyError < StandardError; end
-
-  # 本次写入已经确认交付的进度；其他嵌套写入的异常保留在 cause。
-  class WriteTimeout < IOError
-    # 本次 write 已被底层接受的字节数。
-    attr_reader :bytes_written
-
-    # 构造包含已交付字节数的背压超时。
-    def initialize(message = "write timed out", bytes_written: 0)
-      @bytes_written = bytes_written
-      super(message)
-    end
-  end
-
-  class << self
-    # 创建并启动 Session；有块时返回块结果，并按 graceful 策略关闭所属资源。
-    # raw 只控制本次子进程 PTY；日志与输出对象始终借用。
-    def spawn(*command, env: {}, chdir: nil, raw: false, graceful: false,
-              timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
-      session = nil
-      spawned = false
-      cleanup = lambda do
-        if session && (block_given? || !spawned)
-          session.cleanup_session(nil, writer: nil, own: false, graceful: spawned && graceful)
-        end
-      end
-      Cleanup.always(cleanup) do
-        # 先持有对象再初始化，构造完成到工厂接管之间不能留下无人负责关闭的窗口。
-        session = Session.allocate
-        session.__send__(:initialize, timeout:, write_timeout:, buffer_limit:, logger:, transcript:, outputs:)
-        session.spawn(*command, env:, chdir:, raw:)
-        spawned = true
-        block_given? ? yield(session) : session
-      end
-    end
-
-    # 适配真实 IO；own 只决定读写端点的关闭责任，日志与输出目标仍由调用者管理。
-    # 有块时返回块结果；初始化失败也清理已取得的所属端点。
-    def open(io, writer: io, own: false, graceful: false,
-             timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
-      session = nil
-      initialized = false
-      cleanup = lambda do
-        if session && (block_given? || !initialized)
-          session.cleanup_session(io, writer:, own:, graceful: initialized && graceful)
-        elsif !session && own
-          ResourceOwner.close_handles(io, writer)
-        end
-      end
-      Cleanup.always(cleanup) do
-        session = Session.allocate
-        session.__send__(:initialize_io, io, writer:, own:, timeout:, write_timeout:, buffer_limit:,
-                                             logger:, transcript:, outputs:)
-        initialized = true
-        block_given? ? yield(session) : session
-      end
-    end
-
-    # 按 outputs 建立转发图，返回引发停止的 Session；总期限到达返回 nil。
-    def interconnect(*sessions, timeout: nil)
-      raise ArgumentError, "interconnect requires Session objects" unless sessions.any? && sessions.all?(Session)
-
-      Relay.new(sessions, timeout).run
-    end
-
-    # 共同等待指定来源，返回不可变 Result。consume 控制本轮是否消费匹配文本。
-    # reset_timeout_on_read 仅重置相对期限，deadline 始终是不可延长的总期限。
-    def expect(*patterns, from: [], timeout: nil, deadline: nil, consume: true, reset_timeout_on_read: false, &)
-      run_expect(from, patterns, timeout, deadline:, consume:, reset_timeout_on_read:, &)
-    end
-
-    # 返回回调继续控制符，reset_timeout 为 false 时保留原相对期限。
-    def continue(reset_timeout: true) = reset_timeout ? CONTINUE : CONTINUE_WITHOUT_RESET
-
-    # 当前单调时钟秒数；供跨多次等待共享 deadline。
-    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    # 转换有限非负秒数，nil 表示无相对期限。
-    def duration(value)
-      return nil if value.nil?
-
-      number = Float(value)
-      raise ArgumentError, "duration must be finite and nonnegative" unless number.finite? && number >= 0
-
-      number
-    end
-
-    # 返回可读 Session，不消费输入；去重、排除已关闭来源，并保留声明顺序。
-    def readable_sessions(*sessions, timeout: 0)
-      timeout = duration(timeout)
-      raise ArgumentError, "readable_sessions requires Session objects" unless sessions.all?(Session)
-
-      active = sessions.uniq(&:object_id).reject(&:closed?)
-      return [] if active.empty?
-
-      deadline = timeout && (monotonic + timeout)
-      polled = false
-      ready = nil
-      loop do
-        remaining = deadline && [deadline - monotonic, 0].max
-        return [] if polled && remaining&.zero?
-
-        begin
-          ready = IO.select(active.map(&:to_io), nil, nil, remaining)
-          break
-        rescue Errno::EINTR
-          polled = true
-        end
-      end
-      return [] unless ready
-
-      select_ready_sessions(active, ready.first)
-    end
-
-    private
-
-    # 按对象身份归属就绪描述符，不能用 IO 的值相等规则合并来源。
-    def select_ready_sessions(sessions, readable)
-      by_io = readable.each_with_object({}.compare_by_identity) { |io, index| index[io] = true }
-      sessions.select { |session| by_io.key?(session.to_io) }
-    end
-
-    # 声明完成后固定模式；有参数块保留调用方 self，无参数块使用模式 DSL。
-    def run_expect(sessions, patterns, timeout, deadline:, consume:, reset_timeout_on_read:,
-                   match_by_position: false, &block)
-      timeout = duration(timeout)
-      deadline = Float(deadline) unless deadline.nil?
-      raise ArgumentError, "deadline must be finite" if deadline && !deadline.finite?
-      raise ArgumentError, "provide patterns or a pattern block, not both" if block_given? && !patterns.empty?
-
-      pattern_list = PatternList.new(sessions, patterns)
-      if block
-        block.parameters.empty? ? pattern_list.instance_exec(&block) : block.call(pattern_list)
-      end
-      Matcher.new(pattern_list, timeout, deadline:, consume:, reset_timeout_on_read:, match_by_position:).run
-    end
-  end
-end