expect-pty 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb3b136c8eba8bbce544e17de1d65fd533e0bdd96a57be3c32ae070dfb7a4dfb
-  data.tar.gz: 1133f3426854d0d5f7b9c3695d571fae273ae77bf39e3b218b17d683f5a677e2
+  metadata.gz: 0e21e96f8c4a79123cb7eb74606f0b0a8195c855290ba5ca97b43419917b1e36
+  data.tar.gz: 5f77fab495dd5d5b10e91e14a6957d3907c261cd9931dd73d1113827c1eabc74
 SHA512:
-  metadata.gz: 11e8b10c1e47effa3c4d15c9d876b03964a3002b6caa1d24fa59ffcf6887e06142f8d54409efabd7b8bb794ce3c0be4209f1258b1f815383e662b9e978fd4e0a
-  data.tar.gz: 4afa9e166dba2912c399e9db58c4345fcc284509fbbcfa5306759ae0b31a323b0ae6b97d8c74f90ffede52480c3ed7ca75b6d543b44bfed5daf485c24af7c3ec
+  metadata.gz: b6334c31be027acef464d2d648dec242e43eff2367076a149c64a64a88edd27da2d51a65f3e85afcf2e8d15b2c41439c496b75731cc26db8e816d1fd3296076b
+  data.tar.gz: 1437a5c147513aa572b8b0430d8f25f0ed526ba6b14309f261f0ef30e1f0fa7e2b4850c4abd8a6a35f0988307f204870f31961c26db77245a6d35f986e34babe

data/.rubocop.yml

@@ -7,29 +7,37 @@ AllCops:
     - "tmp/**/*"
     - "vendor/**/*"
 
-# Length and ABC counts are poor signals for protocol loops and integration scenarios.
-# Branch complexity remains checked for production code; reviewed state machines
-# carry local exemptions at the method that needs them.
+# 宽松但有限的规模门槛覆盖生产代码；测试和基准的场景编排不按方法长度及 ABC 计数。
+# 需要更高分支复杂度的协议状态机仅在对应方法说明豁免原因。
 Metrics/AbcSize:
-  Enabled: false
+  Max: 120
+  Exclude:
+    - "test/**/*"
+    - "benchmark/**/*"
 
 Metrics/BlockLength:
-  Enabled: false
+  Max: 80
 
 Metrics/BlockNesting:
-  Enabled: false
+  Max: 4
+  Exclude:
+    - "test/**/*"
 
 Metrics/ClassLength:
-  Enabled: false
+  Max: 500
 
 Metrics/MethodLength:
-  Enabled: false
+  Max: 80
+  Exclude:
+    - "test/**/*"
+    - "benchmark/**/*"
 
 Metrics/ModuleLength:
-  Enabled: false
+  Max: 250
 
 Metrics/ParameterLists:
-  Enabled: false
+  Max: 6
+  CountKeywordArgs: false
 
 Metrics/CyclomaticComplexity:
   Max: 13

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.3.3 - 2026-09-27
+
+- **生命周期**：构造及工厂启动失败时统一释放所属 IO 并回收子进程；块或软关闭的原始异常不再被后续 IO 清理错误覆盖，失败的单个句柄不会阻止其他资源收尾。
+- **匹配期限**：EOF 回调保留原期限继续时，不再于期限过后消费其他来源的文本匹配；已知 EOF 仍依次派发，所有来源结束时保持 EOF 结果。
+- **正则性能**：只在需要调整编码时复制输入缓冲，减少大缓冲区多模式扫描的耗时和分配，保持编码及字节偏移语义。
+- **终端错误**：系统缺少 `stty` 时提供明确的 IO 错误和安装提示，并保留原始异常。
+- **发布校验**：拒绝发布与目标 Git 提交的内容、执行权限或包元数据不一致的 Gem，提交前仍可通过 dry-run 验证候选包。
+
 ## 0.3.2 - 2026-09-26
 
 - **匹配与转接**：正则直接使用字节偏移，重复来源在单轮扫描中共享缓冲快照；转义正则复用本轮组合文本，保留回调修改规则后的重新扫描语义。`send_slow` 只读取已经可读的回复。

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # 参与贡献
 
-欢迎中文或英文 issue 和 PR。API、错误信息和示例中的可编辑命令保持直接清晰；库中的复杂生命周期和协议注释主要使用中文，英文说明同样欢迎。
+欢迎中文或英文 issue 和 PR。库的公共 API 名称和错误信息使用英文；库内的责任划分、复杂生命周期和协议解释使用中文，RuboCop 等工具指令保持原格式。文档以现有文件的语言为准，示例中的可编辑命令保持直接清晰。
 
 ## 本地检查
 
@@ -14,6 +14,8 @@ script/ci                  # 另含示例、Gem 构建及隔离安装验证
 
 修改转接或匹配时，先运行对应的 `test/*_test.rb`，再运行 `bundle exec rake`。默认测试不需要 SSH；真实 SSH 集成测试的环境要求见 [测试说明](test/integration/README.md)。发布操作和历史验证分别见 [发布说明](docs/RELEASING.md) 与 [验证记录](docs/VERIFICATION.md)。
 
+RuboCop 对生产代码保留有限的长度、ABC、嵌套、参数数量和分支复杂度门槛。测试及基准的场景编排豁免方法长度与 ABC 计数；协议状态机的分支豁免只放在对应方法，并注明原因。阈值用于提示复核，职责拆分仍应保持状态归属和异常恢复逻辑完整。
+
 ## 提交问题或改动
 
 问题报告请附 Ruby 版本、操作系统、最小复现代码、预期与实际结果，以及必要的异常信息；日志中请删去凭据和会话敏感内容。修复行为缺陷时，先加入能在旧实现复现问题的回归测试。涉及缓冲、转义、背压或进程清理的改动，请对照 [内部状态与数据归属](docs/INTERNAL_CONTRACTS.md)，说明超时、EOF 和失败后的恢复行为。

data/README.md

@@ -13,7 +13,7 @@
 项目和仓库名为 `expect-ruby`，Gem 名为 `expect-pty`。在应用的 Gemfile 中添加以下内容，然后运行 `bundle install`：
 
 ```ruby
-gem "expect-pty", "~> 0.3.2", require: "expect/pty"
+gem "expect-pty", "~> 0.3.3", require: "expect/pty"
 ```
 
 也可直接执行 `gem install expect-pty`。需要跟随开发分支时，可从 GitHub 安装：
@@ -26,8 +26,8 @@ gem "expect-pty", git: "https://github.com/gatework/expect-ruby.git", branch: "m
 
 ```sh
 mkdir -p tmp
-gem build expect-pty.gemspec --output tmp/expect-pty-0.3.2.gem
-gem install ./tmp/expect-pty-0.3.2.gem
+gem build expect-pty.gemspec --output tmp/expect-pty-0.3.3.gem
+gem install ./tmp/expect-pty-0.3.3.gem
 ```
 
 ```ruby
@@ -45,7 +45,7 @@ Expect.spawn("/bin/sh", "-i") do |shell|
 end
 ```
 
-块返回其执行结果，退出时关闭会话并回收子进程，异常和 `break` 也执行清理。无块形式需用 `ensure` 显式调用 `close`。`Expect.new` 可以先创建 PTY、设置 `slave.echo` / `slave.winsize`，然后调用实例的 `spawn`。
+块返回其执行结果，退出时关闭会话并回收子进程，异常和 `break` 也执行清理。构造或启动失败时同样释放已创建的资源；清理中的 IO 错误不会替换正在传播的原始异常。无块形式需用 `ensure` 显式调用 `close`。`Expect.new` 可以先创建 PTY、设置 `slave.echo` / `slave.winsize`，然后调用实例的 `spawn`。
 
 多个命令参数原样传给 Ruby `exec`；单个命令字符串使用 Ruby 的 shell 语义。不可信参数应使用独立参数形式。支持 `env: { "NAME" => "value" }` 和 `chdir: "/path"`。同一会话只能启动一次，启动失败抛出 `Expect::SpawnError`。
 
@@ -71,6 +71,8 @@ end
 
 `configure` 校验后发布冻结的配置对象；块异常不会发布部分修改。并发调用按顺序完成读改写，不会互相覆盖不同属性。配置块在锁内执行，应保持简短，不要在块内再次调用 `configure`（会抛出 `ThreadError`）或等待其他配置线程。每个会话独立持有配置，优先使用构造参数；修改默认值不会改变已有会话，修改一个会话也不会影响其他会话。子类继承父类默认配置，可独立覆盖。
 
+全局默认配置通常在应用启动时设置；每次会话的动态差异使用构造参数或会话属性，避免在高频路径反复获取共享配置锁。
+
 | 属性 | 默认值 | 行为 |
 | --- | --- | --- |
 | `timeout` | `nil` | 等待匹配的默认超时，秒；`nil` 无限，`0` 非阻塞轮询 |
@@ -143,7 +145,7 @@ end
 
 回调通过闭包访问局部变量。无参数声明块在模式构建器中执行；希望保留调用方 `self` 时使用 `do |patterns|`，调用 `patterns.on(...)`。所有模式注册完成后才读取 IO；注册异常或 `break` 不消费输入。块和位置模式不能混用。`expect_result` 支持同样的声明方式。
 
-`continue` 继续等待并重新计时；`continue(reset_timeout: false)` 保留原期限，类和实例均可调用。无回调或返回其他值时结束本次匹配。超时回调只有返回重置计时的 `continue` 才再次等待。EOF 回调继续时移除该源并等待其余会话，全部 EOF 时立即返回。
+`continue` 继续等待并重新计时；`continue(reset_timeout: false)` 保留原期限，类和实例均可调用。回调返回后若保留的期限已过，不再扫描新的文本匹配，未消费的输入留给下一次等待。无回调或返回其他值时结束本次匹配。超时回调只有返回重置计时的 `continue` 才再次等待。EOF 回调继续时移除该源并等待其余会话；已知的 EOF 仍依次派发，全部 EOF 时直接返回，期限已过时仅对剩余活跃源触发超时。
 
 `eof` / `timeout` 声明会占用模式序号，但事件返回的 `number` 为 `nil`。一个等待只能注册一个超时回调；它接收**所有仍在监听的会话**。不需要回调时，可将 `:eof` / `:timeout` 作为位置事件参数。
 
@@ -193,6 +195,8 @@ ready = Expect.readable_sessions(first, second, timeout: 5)
 
 大块写入遇到背压时同时读取输出，避免双向传输互相阻塞。超过 `write_timeout` 抛出 `Expect::WriteTimeout`，`error.bytes_written` 给出本次 `write` 已被底层接受的字节数；这些字节不回滚，不要从头重发整个命令。写入、等待和背压读取中的 `EINTR` 均保留原期限重试。控制字符可直接发送，例如 `session.write("\x03")`，其信号作用取决于终端设置。`send`、`public_send`、`__send__` 保留 Ruby 反射语义。
 
+`stty` 需要系统命令位于 `PATH`；缺失时抛出带安装提示的 `IOError`，原始 `Errno::ENOENT` 保留在 `cause`。窗口尺寸和人工接管的终端恢复使用 Ruby `io/console`。
+
 ## 日志与人工交互
 
 ```ruby
@@ -210,6 +214,8 @@ session.log_listeners = false
 
 所有会话默认不输出到 stdout。日志仅记录实际读取的接收字节；写入不重复记录，终端回显可能作为接收内容返回。密码交互应关闭日志、调试，并确保被控程序不回显密码。
 
+普通 `expect` 按顺序同步写入日志、stdout 和 `listeners`，这些目标须及时消费数据；匹配的 `timeout` 不会中断阻塞中的输出。需要在慢目标背压时继续处理其他输入，应使用下面的 `interconnect` 非阻塞转接接口并设置期限。
+
 ```ruby
 session.interact(input: $stdin, escape: "\x1d", output: $stdout) # Ctrl-]
 

data/docs/COMPATIBILITY.md

@@ -24,7 +24,7 @@
 
 交互能力参考 [jacoby/expect.pm](https://github.com/jacoby/expect.pm)，源码基准为版本 1.38、提交 `2ea0e4ce20a896c95cb4c94e781f1b1f3145150d`。此项目独立实现，使用 MIT 许可，没有复制 Perl 实现代码；原项目作者及维护者为 Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。
 
-当前未发布版本采用 Ruby 原生接口。下表列出迁移关系，**旧方法、别名和参数语法已移除**；历史 0.1.1 安装包的接口见对应版本记录。
+从 0.2.0 起采用 Ruby 原生接口。下表列出迁移关系，**旧方法、别名和参数语法已移除**；历史 0.1.1 安装包的接口见对应版本记录。
 
 | 原接口或状态 | 当前 Ruby 接口 |
 | --- | --- |

data/docs/INTERNAL_CONTRACTS.md

@@ -2,6 +2,21 @@
 
 这些状态供 Matcher、Relay 和会话生命周期协作使用，不是公共接口。
 
+## 模块职责
+
+| 模块 | 职责 |
+| --- | --- |
+| `expect.rb` | 会话入口、PTY 启动、缓冲、直接读写和关闭流程 |
+| `configuration.rb` | 配置校验与可复制的默认快照 |
+| `pattern.rb`、`pattern_list.rb`、`result.rb` | 字节定位、声明顺序及原生结果值 |
+| `matcher.rb` | 一次等待的匹配、事件派发和期限 |
+| `session_resources.rb` | IO、日志与直属子进程的所有权账本和 GC 兜底 |
+| `logging.rb` | 日志目标、监听器及同步输出；不持有第二份资源所有权 |
+| `terminal.rb` | `stty` 和窗口尺寸的会话终端接口 |
+| `interaction.rb`、`relay.rb`、`relay_writer.rb` | 人工接管、转义处理、共同调度和各目标发送游标 |
+
+这些能力文件延续 `interaction.rb` 的类重开方式，公共入口仍是 `expect/pty`。按职责组织方法，不引入新的继承层级，也不复制会话状态。
+
 跨对象调用使用 `__send__` 访问受保护或私有方法。变更以下入口时，应同时检查调用方与失败恢复路径：
 
 | 会话内部入口 | 使用方 | 不变量 |
@@ -22,14 +37,20 @@
 
 匹配优先级始终是“声明组 → 会话 → 模式”，不是文本位置；多个会话包装同一 IO 时，就绪处理使用对象身份选择首个声明会话。回调前后用于判断缓冲是否变化的快照仍独立保留，不能换成可变内部字符串。零长度或 preserve_buffer 的继续匹配必须遵守 stalled 保护。
 
+文本与 EOF 回调遵守相同的继续期限：`continue(reset_timeout: false)` 返回后先检查原期限，再开始下一轮文本匹配。EOF 继续已到期时仍依次派发已知 EOF，不读取新输入；超时仅通知仍活跃的来源，保留未消费缓冲。所有来源都已 EOF 时直接返回 EOF，不再制造一次超时事件。EOF 或超时回调重置期限后恢复普通匹配顺序。
+
 转义扫描只在一轮内复用 `history + buffer`，只含字面规则时不构造它。回调继续后重新读取规则、历史和缓冲；不能跨回调保存文本快照。字面转义的潜在前缀暂存，完整前缀交付后才执行转义回调。
 
 ## 关闭与所有权
 
 SessionResources 保存创建者 PID、所属句柄、直属子进程和所属日志。借用 IO 不关闭，fork 后的非创建者不发送信号或回收父进程的孩子。soft_close 最多发送 TERM 并保留未退出 PID；hard_close 可在有限等待后发送 KILL。
 
+工厂和构造器在校验之前登记资源归属，失败时沿用同一清理流程；启动成功必须显式记录，不能用 PID 非空推断整个工厂调用已经成功。即使 exec 成功后诊断输出失败，也要立即回收未交付给调用方的子进程。
+
 显式关闭遇到 IOError/SystemCallError 时，继续尝试其他句柄、交互包装器、日志和子进程清理，最后传播首个清理错误；已经在传播的其他异常保留。失败资源继续持有，后续关闭可重试。GC 终结器独立尝试句柄、日志、非阻塞回收，常规清理错误不向外传播。终结器不能强引用会话本身。
 
+是否保留原始异常由当前构造、块或关闭作用域显式记录，不能直接读取调用者 rescue 中的 `$!`。`Interrupt` 和 `SystemExit` 同样先清理再传播；`break` / `throw` 不是异常，此时清理失败仍应抛出。
+
 ## 回归入口
 
 | 不变量 | 测试 |

data/docs/PERFORMANCE.md

@@ -35,6 +35,22 @@ bundle exec ruby benchmark/matching.rb --samples 5 --output tmp/benchmark/after.
 
 没有 Git 的源码归档或安装目录仍可运行；提交和工作区状态记为 `null`，保留源码 SHA-256。
 
+## 正则输入复用验证（2026-09-27）
+
+`Pattern#locate` 只在正则要求的编码与输入编码不同时复制输入；其他正则复用只读缓冲。Ruby 字符串可能共享底层存储，因此不能把减少一次 `dup` 直接解释为少复制整个缓冲的字节数；这里报告实际对象分配和墙钟样本。
+
+macOS arm64、Ruby 4.0.6、Bundler 4.0.17，使用同一套 `benchmark/matching.rb` 和依赖，对修改前后的 `lib` 分别运行 `--samples 5 --iterations 100`。下表为五次样本的中位数，每项均校验匹配结果。此前用 30 次迭代进行的首轮比较方向一致。
+
+| 场景 | 修改前耗时 | 修改后耗时 | 修改前分配 | 修改后分配 |
+| --- | --- | --- | --- | --- |
+| 4 KiB、32 个正则、全未命中 | 1.985 ms | 1.415 ms | 6,501 | 3,301 |
+| 64 KiB、32 个正则、全未命中 | 17.068 ms | 11.070 ms | 6,501 | 3,301 |
+| 1 MiB、32 个正则、全未命中 | 257.474 ms | 165.734 ms | 6,501 | 3,301 |
+| 1 MiB、32 个正则、最后命中 | 265.848 ms | 172.001 ms | 7,301 | 4,101 |
+| 1 MiB UTF-8 前缀、固定编码正则 | 78.348 ms | 74.721 ms | 1,201 | 1,201 |
+
+固定 UTF-8 正则仍需要编码副本，分配量不变；约 4.6% 的耗时差不能视为稳定收益。单正则大缓冲场景也基本不变。上述结果适用于本次机器与工作负载，不设为 CI 性能门槛。
+
 ```sh
 bundle exec ruby benchmark/matching.rb --smoke
 bundle exec ruby benchmark/relay.rb --smoke

data/docs/RELEASING.md

@@ -4,8 +4,8 @@
 
 ## 准备版本
 
-1. 更新 `lib/expect/version.rb` 的 `Expect::VERSION`，例如 `0.3.2`。
-2. 把 `CHANGELOG.md` 的 `Unreleased` 内容移到对应版本标题下，例如 `## 0.3.2 - 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.2 -m 'Release v0.3.2'
-git push origin v0.3.2
-gh workflow run release.yml --ref v0.3.2 --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.2 --repo gatework/expect-ruby
 保留脚本输出的 `Artifact` 路径，用该候选 Gem 重试发布；更换 RubyGems 工具版本或重新构建可能得到不同字节，同一个版本不得覆盖已有内容。也可以直接指定从 CI 或 Release 下载的原包：
 
 ```sh
-ruby script/release.rb --rubygems-only --artifact tmp/ci/expect-pty-0.3.2.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,21 @@
 # 验证记录
 
+## 模块审查、资源清理与正则输入复用（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 模板与安全说明。

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
@@ -196,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?
 
@@ -204,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
@@ -109,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 重试不重新计时。
@@ -182,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)

data/lib/expect/session_resources.rb

@@ -19,9 +19,9 @@ class Expect
     def close_handles
       return unless own
 
-      # PTY 的读写端可能是同一个对象，先去重，重复关闭也保持安全。
+      # 初始化校验失败时可能含无效参数，只关闭真实 IO；PTY 读写端也需要去重。
       failure = nil
-      [reader, writer, slave].compact.uniq.each do |io|
+      [reader, writer, slave].grep(IO).uniq.each do |io|
         io.close unless io.closed?
       rescue IOError, SystemCallError => error
         failure ||= error

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.2"
+  VERSION = "0.3.3"
 end