expect-pty 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ed8a06887893ae6dff3edc0e378cfea6ae3b2c05b5800f7f00096b3d2389ecd
-  data.tar.gz: b8d38b25c886080b2883d6c823087bb3962185b2a2cf414222eff8ffbf8b4d2a
+  metadata.gz: eda03bcece07a45c1c1f4f4010ae389928db6954b44624d072ce0e4249ee5a4d
+  data.tar.gz: df16127b3002243113a3f4bb6f1945ebb5430a4a1ba614e1926f5c4be17c6a0b
 SHA512:
-  metadata.gz: 7ed8785fd0f71ffbccaad9057248eb4f8aff91b9bab1b7b562eb63f9e6210149303e86c516921f4ba452239407220a048e4f8c2fefdcf9d4efb05de21011f23f
-  data.tar.gz: 938c119f3c43bee28e94f16f72029e34c506882f2ce50b118cb739fbefcac454689d8f9cf6552c68572b27c05661e2d0df7954ab8720a3876797910209806e73
+  metadata.gz: 0aab6a9174549cac6cbdfd33eb658b4027c6509bc9a8f246d48d76329fd9c8594e38bfc0f03430f2121bbdc82b7810f89b329c5f05051ea2657c2d0498e12825
+  data.tar.gz: d819201280329ce39678db25c32d4657336b2e2e0288945285377b90d309e30aa616a60847024a1aeccf157eedbfd32165e6b01caba7e4c8c66b357c72656e3b

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.3.0 - 2026-09-26
+
+- **终端模式调整**：通用 `interconnect` 改由调用方设置和恢复终端模式，需要自动切换本地输入终端时使用 `interact`，直接转接终端的现有代码需要相应调整。
+- **转接恢复**：真实 IO 的背压受转接总期限和目标写期限约束，超时、短写入或监听器失败后可继续发送未完成的后缀，`pending_output?` 可查询待发送状态。
+- **输入与写入**：重复 `interact` 会接续同一输入 IO 的预读尾部，背压输入保留转义过滤，`WriteTimeout#bytes_written` 提供写入进度，临时 `EINTR` 不再中断原操作或重置期限。
+- **匹配与编码**：固定 UTF-8 正则等待分片字符收齐，非法或 EOF 截断编码抛出 `EncodingError` 并保留原字节，无进展回调等待新输入，正则转义默认只保留最近 65,536 字节历史。
+- **日志与回收**：新建日志默认权限为 `0600`，日志异常后接收数据仍可恢复，捕获会话的日志回调不再阻止子进程的 GC 回收。
+- **重复接管与回调**：切换退出正则不再匹配已转发的旧输入，相同终端的跨次 CRLF 保持原样，转义回调可用 `expect` 消费预读尾部和新回复，嵌套输出超时保留调用方的写入进度。
+
 ## 0.2.0 - 2026-09-13
 
 - **不兼容变更**：接口统一采用 Ruby 属性、谓词、关键字参数、原生正则和块回调，移除 `exp_*`、`get/set_accum`、位置超时和数组回调等旧入口，不提供兼容别名，迁移方式见 `docs/COMPATIBILITY.md`。

data/README.md

@@ -78,7 +78,7 @@ end
 | `preserve_buffer` | `false` | 匹配后保留完整缓冲 |
 | `log_stdout` | `false` | 将接收内容输出到 `$stdout` |
 | `log_listeners` | `true` | 将接收内容转发给 `listeners` |
-| `raw_terminal` | `true` | 转接期间自动设置并恢复终端 raw 模式 |
+| `raw_terminal` | `true` | `interact` 期间自动设置并恢复输入终端模式，同时保留输出换行处理 |
 | `reset_timeout_on_read` | `false` | 每次收到数据时重置匹配期限 |
 | `graceful_close` | `false` | `close` 先尝试软关闭，再完成强制清理 |
 
@@ -114,10 +114,12 @@ number, error, match, before, after, session, captures = result.to_a
 
 成功匹配后删除匹配内容及其之前的内容，尾部留给下次匹配；超时保留缓冲，EOF 将未匹配内容放入 `before` 并清空缓冲。EOF 与子进程退出是不同事件，使用 `wait` / `process_status` 判断进程结果。底层 IO 错误保留原始异常，回调中的普通异常直接抛出。
 
-接收缓冲、匹配和捕获值为 `ASCII-8BIT` 字节串，保留控制字符、NUL 和无效 UTF-8。UTF-8 正则支持跨读取拆开的字符；显示捕获内容时可 `.force_encoding("UTF-8")`。任意二进制流请用字面字符串或二进制正则 `/.../n`。固定 UTF-8 正则遇到无效数据抛出 `EncodingError`。缓冲上限按字节截断，应为文本设置足够的上限。
+接收缓冲、匹配和捕获值为 `ASCII-8BIT` 字节串，保留控制字符、NUL 和无效 UTF-8。固定 UTF-8 正则会等待读取末尾拆开的字符收齐后再匹配，以免尾部锚点提前命中；显示捕获内容时可 `.force_encoding("UTF-8")`。任意二进制流请用字面字符串或二进制正则 `/.../n`。固定 UTF-8 正则遇到无效数据抛出 `EncodingError`；EOF 时仍未收齐的字符也属于无效编码，匹配缓冲保留原字节供诊断或二进制匹配。缓冲上限按字节截断，应为文本设置足够的上限。
 
 正则完全遵循 Ruby：`^` / `$` 是行锚点，`\A` / `\z` 是整个缓冲的锚点，`/m` 让点号匹配换行；不再提供全局正则模式开关。
 
+IO 等待的 `timeout` 不会中断单次正则计算。处理用户提供的正则或不可信长输出时，应使用有限时的正则实例，例如 `Regexp.new('prompt>\\s*', timeout: 0.05)`；该限制同样适用于 `on_sequence`。正则超时原样抛出 `Regexp::TimeoutError`，匹配缓冲保留，库不会修改进程全局 `Regexp.timeout`。`timeout: 0` 仍会匹配已有缓冲，不代表禁止正则计算。长输出可用日志保存全文，按业务需要设置 `buffer_limit` 限制匹配窗口；缩小窗口会改变 `before` 和跨窗口匹配范围。
+
 ## 回调、事件与多会话
 
 ```ruby
@@ -153,7 +155,7 @@ Expect.expect("ready", from: [first, second], timeout: 5)
 
 `from:` 指定一个或多个会话；实例块默认当前会话，类方法需提供来源。相邻且来源列表相同的模式组成一组，按组、会话、模式顺序匹配。类方法省略超时使用 `Expect.configuration.timeout`。
 
-`preserve_buffer = true` 时，继续回调应自行消费匹配，例如 `connection.buffer = connection.after`，避免重复匹配同一内容。无限超时与不消费缓冲的继续回调可以无限循环。被信号中断的匹配 select/read 会自动重试，保留原期限。
+`preserve_buffer = true` 时，继续回调通常应自行消费匹配，例如 `connection.buffer = connection.after`。如果回调没有改变缓冲，当前模式会等待缓冲变化后才重新匹配，避免反复处理同一内容。被信号中断的匹配 select/read 会自动重试，保留原期限。
 
 ## 已有 IO、写入和终端
 
@@ -168,6 +170,8 @@ ready = Expect.readable_sessions(first, second, timeout: 5)
 
 `Expect.open` 支持可 `select` 的 File、管道、Socket 和 PTY，`writer:` 可指定独立写端。默认借用 IO，关闭会话不关闭原始 IO；`own: true` 转移关闭责任，初始化失败也会释放接管的 IO。`StringIO` 可以用作日志和监听器，不能用作读取会话。
 
+用于写入或转接的真实 IO 应在首次写入前设置 `io.sync = true`，并由调用方保证没有未刷新的 Ruby 写缓冲；`write_nonblock` 可能先阻塞刷新已有缓冲，这一步不受本库的 IO 等待期限控制。已有缓冲应在交付给本库前由调用方排空，库不会绕过缓冲或改变字节顺序。
+
 `readable_sessions` 返回可读的会话对象数组，不消费数据、不包含已关闭会话、同一会话只返回一次。默认 `timeout: 0`；`nil` 无限等待。同一会话应由一个读取者驱动，多会话共同监听使用 `Expect.expect`。
 
 | API | 行为 |
@@ -182,7 +186,7 @@ ready = Expect.readable_sessions(first, second, timeout: 5)
 | `winsize` / `winsize=` | 读取/修改 `[rows, cols]`，由内核通知前台进程 |
 | `slave` / `tty_name` / `to_io` / `writer` / `fileno` / `tty?` | 底层 IO 和终端信息 |
 
-大块写入遇到背压时同时读取输出，避免双向传输互相阻塞。超过 `write_timeout` 抛出 `Expect::WriteTimeout`，已写入字节不回滚。控制字符可直接发送，例如 `session.write("\x03")`，其信号作用取决于终端设置。`send`、`public_send`、`__send__` 保留 Ruby 反射语义。
+大块写入遇到背压时同时读取输出，避免双向传输互相阻塞。超过 `write_timeout` 抛出 `Expect::WriteTimeout`，`error.bytes_written` 给出本次 `write` 已被底层接受的字节数；这些字节不回滚，不要从头重发整个命令。写入、等待和背压读取中的 `EINTR` 均保留原期限重试。控制字符可直接发送，例如 `session.write("\x03")`，其信号作用取决于终端设置。`send`、`public_send`、`__send__` 保留 Ruby 反射语义。
 
 ## 日志与人工交互
 
@@ -197,7 +201,7 @@ session.listeners = [output_io, another_session]
 session.log_listeners = false
 ```
 
-日志读取用 `log_output`，设置用 `log_output=`，打开路径或注册日志块用 `log_to`。不能同时提供日志目标与块。`listeners` 返回列表副本，`listeners = []` 清空；替换无效目标不会丢失原目标。
+日志读取用 `log_output`，设置用 `log_output=`，打开路径或注册日志块用 `log_to`。新建日志权限为 `0600`（仍受 umask 限制），已有文件保留原权限。不能同时提供日志目标与块。`listeners` 返回列表副本，`listeners = []` 清空；替换无效目标不会丢失原目标。
 
 所有会话默认不输出到 stdout。日志仅记录实际读取的接收字节；写入不重复记录，终端回显可能作为接收内容返回。密码交互应关闭日志、调试，并确保被控程序不回显密码。
 
@@ -214,9 +218,17 @@ end
 
 `on_sequence(sequence) { ... }` 注册字符串、原生正则或 `:eof`，通过闭包传递参数。无回调、返回 `nil` / `false` 停止，其他 Ruby 真值（包括 `0`）继续；字符串 `"EOF"` 按字面匹配。转接返回导致停止的会话，超时或所有 EOF 回调均继续时返回 `nil`。
 
-字面转义可以跨读取完整过滤，尾部留给下次调用。正则转义使用受 `buffer_limit` 限制的历史记录，已实时转发的前缀无法撤回；零长度正则匹配抛出 `ArgumentError`。日志始终记录原始接收字节，包括被过滤的转义，在 `expect` / `interconnect` 之间切换也不会重复记录。
+`interconnect` 统一调度真实 IO 的非阻塞读写；慢目标不会阻止其他源前进，等待同时受总 `timeout` 和目标会话的 `write_timeout` 约束。总期限到达返回 `nil`，目标写期限先到则抛出 `WriteTimeout`。超时后的字面转义前缀只尝试非阻塞发送，不再等待下游。作为写入目标但未显式列出的 Expect 会话，背压期间读取的回复保留在其匹配缓冲；需要同时转发这些回复时，把它也传给 `interconnect`。
+
+每个源独立保存待发送数据以及各目标的发送位置，`source.pending_output?` 表示仍有未交付内容。超时或异常后再次对同一源调用 `interconnect`，会接着发送未完成的后缀，已完成的目标不会重复接收；转义回调在前缀交付后执行。待发送数据与 `buffer` 中尚未处理的输入分开保存，修改 `listeners` 仅影响后续数据，旧数据仍发往原目标。恢复时不要把原始数据再次赋给 `buffer`，也不要在排空旧输出前插入新的直接写入；关闭源会话会放弃其待发送数据。转接保留的输入暂不按 `buffer_limit` 裁剪，下次匹配时重新应用该上限。
+
+自定义写入对象必须及时返回实际接受的字节数，短写入会继续发送后缀，零、负数或非法返回值抛出 `IOError`。对象若先写入再抛错而不报告进度，库无法推断其副作用。日志、用户回调及自定义 `write` / `flush` 同步运行，应由调用方保证它们不会无限阻塞；上述 IO 期限不会强行中断这些代码。普通 `expect` 的同步日志和监听器输出也不受匹配等待期限限制。
+
+字面转义可以跨读取完整过滤，尾部留给下次调用。正则转义使用历史记录，默认最多保留最近 65,536 字节；设置 `buffer_limit` 后改用该值。正则及其锚点作用于当前历史窗口，超过窗口的跨读取正则无法匹配，已实时转发的前缀也无法撤回；零长度正则匹配抛出 `ArgumentError`。日志始终记录原始接收字节，包括被过滤的转义，在 `expect` / `interconnect` 之间切换也不会重复记录。
+
+`interact` 会自动设置并恢复本地输入终端模式，同时保留输出换行处理；输入会话的 `raw_terminal = false` 将设置交给调用方。通用的 `interconnect` 只负责字节转发，由调用方管理终端模式。`interact` 还会恢复临时监听组、日志开关和转义设置，包括超时和异常路径。
 
-转接会自动设置并恢复终端 raw 模式；`raw_terminal = false` 将设置交给调用方。`interact` 还会恢复临时监听组、日志开关和转义设置，包括超时和异常路径。
+对同一连接重复传入同一个原始输入 IO 时，`interact` 会复用输入包装器，接续上次预读的尾部。包装器由该连接持有，关闭连接时释放，但不关闭借用的原始 IO；已关闭的输入或包装器不再复用。需要跨连接共享或自行管理输入生命周期时，显式传入 `Expect.open(input)` 创建的会话。
 
 ## 软关闭、硬关闭与进程状态
 
@@ -253,12 +265,13 @@ ruby examples/ssh_interact.rb --auto
 
 [GitHub Actions](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml) 在推送 `main`、推送 `v*` 标签、提交到 `main` 的 Pull Request 或手动触发时运行。流水线覆盖 Ubuntu 24.04 / macOS 15 与 Ruby 3.2、3.3、3.4、4.0 的 8 种组合；每个环境执行 `script/ci`，包括真实 PTY 测试和构建包的隔离安装验证。Ubuntu / Ruby 4.0 作业保留已验证的 Gem 构建产物 14 天，可从该次工作流的 Artifacts 下载。
 
-运行前先执行 `bundle install`。Gem 库的开发锁文件 `Gemfile.lock` 保留在本地，各 Ruby 环境按 `Gemfile` 解析兼容依赖。生成文件写入已忽略的 `pkg/ci/` 和 `tmp/`。更新工作流中的 Action 时，应同步更新固定的提交 SHA 和版本注释。
+运行前先执行 `bundle install`。Gem 库的开发锁文件 `Gemfile.lock` 保留在本地，各 Ruby 环境按 `Gemfile` 解析兼容依赖。生成文件写入已忽略的 `tmp/`，Gem 构建产物位于 `tmp/ci/`，发布候选包位于 `tmp/release/`。更新工作流中的 Action 时，应同步更新固定的提交 SHA 和版本注释。
 
-版本发布使用 `ruby script/release.rb`，直接复用本机已有的 Gem 和 GitHub 登录状态；脚本会完成验证、创建 GitHub Release 并推送同一个 Gem 到 RubyGems。也可以在 GitHub Actions 手动运行 Release 工作流。版本准备、Actions 凭据和失败重试见 [发布说明](docs/RELEASING.md)。
+仅发布 RubyGems 使用 `ruby script/release.rb --rubygems-only`，直接复用本机已有的 Gem 登录状态；添加 `--dry-run` 可先完成本地检查、测试、构建和安装验证。需要同时创建 GitHub Release 时使用 `ruby script/release.rb`，也可以在 GitHub Actions 手动运行 Release 工作流。版本准备、Actions 凭据和失败重试见 [发布说明](docs/RELEASING.md)。
 
 SSH 示例用 `SSH_USER`、`SSH_HOST`、`SSH_KNOWN_HOSTS` 配置，密码隐藏输入或从 `EXPECT_PASSWORD` 读取；非本地主机要求受信任的 known_hosts 文件。`ssh_auto.rb` 顶部 `COMMANDS` 可直接修改，日志写入 `tmp/ssh-auto/`，权限 0600。
 
 多脚本验证入口为 `test/integration/ssh_scripts.rb`，人工/自动接管入口为 `examples/ssh_interact.rb`，详细配置及日志检查见 [SSH 测试说明](test/integration/README.md)。
 
 当前接口迁移表见 [接口说明](docs/COMPATIBILITY.md)，本次与历史验证分列在 [验证记录](docs/VERIFICATION.md)。此次重构直接移除了旧入口，不提供兼容别名。
+防火墙连接器已迁移到相邻的 `algosec` 项目；本库只保留 `Expect` 与 `expect-pty` 通用传输能力。

data/docs/COMPATIBILITY.md

@@ -1,4 +1,26 @@
-# Ruby 接口与 Expect.pm 行为对照
+# Ruby 接口与 Expect 行为对照
+
+## Tcl Expect 语义边界
+
+参考 Tcl Expect 的[官方手册](https://core.tcl-lang.org/expect/doc/trunk/expect.man)、
+[`expect.c`](https://core.tcl-lang.org/expect/raw/expect.c?ci=trunk) 的 `eval_cases` / `expMatchProcess` / 计时循环，
+以及 [`exp_inter.c`](https://core.tcl-lang.org/expect/raw/exp_inter.c?ci=trunk) 的 `intMatch` 与终端恢复流程。
+本库借鉴交互模型，保留以下明确差异，不承诺 Tcl 脚本或完整功能兼容。
+
+| Tcl Expect 能力 | 本库的 Ruby 表达与边界 |
+| --- | --- |
+| `spawn`、`send`、`expect`、`interact` | PTY 会话、`write` / `puts`、原生模式块和人工接管；`send` 保留 Ruby 反射语义 |
+| `exp_continue` / `-continue_timer` | `continue` / `continue(reset_timeout: false)`；使用单调时钟和秒数关键字参数 |
+| 匹配后消费输入、`-notransfer` | `before` / `match` / `after` 与会话级 `preserve_buffer`；无进展回调不会原地重复执行 |
+| glob、exact、regexp 模式 | 字符串只作字面匹配，正则采用 Ruby `Regexp`；锚点和多行行为遵守 Ruby |
+| `match_max`、`full_buffer` | `buffer_limit` 只保留尾部字节，默认无限；没有缓冲满事件或丢弃字节结果，不能作为完整输出存储 |
+| 前置/后置模式、后台匹配 | 没有全局隐式规则或后台读取器；调用方显式组合模式块，每个会话由一个读取者驱动 |
+| `interact` 的部分正则匹配 | Tcl 的 `CANMATCH` 可以暂存潜在匹配；Ruby 原生正则不提供该接口，本库使用有限历史窗口，已转发前缀不能撤回。需要完整过滤时使用字面转义 |
+| `close` 与 `wait` | IO 结束与进程退出仍分开判断；本库的块生命周期和 `close` 会额外回收直属子进程 |
+
+长输出任务应通过日志或监听器流式保存，并按提示长度设置 `buffer_limit`。需要无损截断通知时，后续应单独设计缓冲满事件，不能把现有尾部裁剪当成该功能。后台匹配与共享前置/后置模式也需要独立的取消、优先级和资源归属约定，尚未实现。
+
+## Expect.pm 接口迁移
 
 交互能力参考 [jacoby/expect.pm](https://github.com/jacoby/expect.pm)，源码基准为版本 1.38、提交 `2ea0e4ce20a896c95cb4c94e781f1b1f3145150d`。此项目独立实现，使用 MIT 许可，没有复制 Perl 实现代码；原项目作者及维护者为 Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。
 

data/docs/RELEASING.md

@@ -1,29 +1,40 @@
 # 发布版本
 
-项目名为 `expect-ruby`，RubyGems 名为 `expect-pty`。发布脚本会创建 GitHub Release，附带 Gem 和 `SHA256SUMS`，并把同一个 Gem 推送到 RubyGems。
+项目名为 `expect-ruby`，RubyGems 名为 `expect-pty`。使用 `script/release.rb --rubygems-only` 可仅发布 RubyGems；不加该选项时还会创建 GitHub Release，附带同一个 Gem 和 `SHA256SUMS`。生成文件统一放在已被 Git 忽略的 `tmp/` 下。
 
 ## 准备版本
 
 1. 更新 `lib/expect/version.rb` 的 `Expect::VERSION`，例如 `0.2.0`。
 2. 把 `CHANGELOG.md` 的 `Unreleased` 内容移到对应版本标题下，例如 `## 0.2.0 - 2026-09-13`；可以保留空的 `Unreleased` 标题。
-3. 提交并推送到 `main`。发布时工作区必须干净，远端 `main` 必须包含该提交，已有同名标签必须指向该提交。
+3. 提交源码，发布时工作区必须干净。若同时发布 GitHub Release，还需推送到 `main`，远端 `main` 必须包含该提交，已有同名标签必须指向该提交。
 
 发布脚本只接受正式版 `X.Y.Z`；未归档的变更会阻止发布。
 
-## 本地发布
+## 仅发布 RubyGems
 
-本地已登录 `gem` 时，脚本直接使用已有凭据；GitHub 使用 `gh auth login` 的登录状态。如果 RubyGems 要求一次性验证码，`gem push` 会提示输入。
+本地已登录 `gem` 时，脚本直接使用已有凭据。如果 RubyGems 要求一次性验证码，`gem push` 会提示输入。此模式不调用 `gh`，不要求推送到 GitHub，也不创建标签或 GitHub Release。
 
 ```sh
 bundle install
-ruby script/release.rb --dry-run
-ruby script/release.rb
+ruby script/release.rb --rubygems-only --dry-run
+ruby script/release.rb --rubygems-only
 ```
 
-默认执行 `script/ci` 的检查、完整测试、构建和隔离安装验证，再把 Gem 复制到 `pkg/release/版本号/candidate-*/` 的独占目录，核对包内文件并生成发布说明和校验文件。该副本贯穿后续发布，目录会保留供失败重试。正式发布先创建 GitHub Release，再上传 RubyGems，最后下载 RubyGems 上的包核对 SHA256。GitHub 上还没有标签时，会为当前提交创建 `v版本号` 标签。
+默认执行 `script/ci` 的检查、完整测试、构建和隔离安装验证，构建包保存在 `tmp/ci/expect-pty-版本号.gem`。随后复制到 `tmp/release/版本号/candidate-*/` 的独占目录，核对包内文件并生成发布说明和校验文件。该副本贯穿后续发布，目录会保留供失败重试。正式发布前再次确认源码未变，上传 RubyGems 后下载远端包核对 SHA256。
 
 `--dry-run` 只做本地验证，可在提交前使用。它仍要求版本号和发布说明完整。
 
+## 同时发布 GitHub Release
+
+此模式还会复用 `gh auth login` 的登录状态：
+
+```sh
+ruby script/release.rb --dry-run
+ruby script/release.rb
+```
+
+正式发布先创建 GitHub Release，再上传 RubyGems，最后下载 RubyGems 上的包核对 SHA256。GitHub 上还没有标签时，会为当前提交创建 `v版本号` 标签。
+
 ## GitHub Actions 发布
 
 GitHub Runner 不会继承本机的 Gem 登录状态。要在 Actions 发布 RubyGems，需在仓库的 Settings → Secrets and variables → Actions 中配置 `RUBYGEMS_API_KEY`，使用具有 `Push rubygem` 权限的发布 Key。
@@ -45,9 +56,11 @@ gh workflow run release.yml --ref v0.2.0 --repo gatework/expect-ruby
 保留脚本输出的 `Artifact` 路径，用该候选 Gem 重试发布；更换 RubyGems 工具版本或重新构建可能得到不同字节，同一个版本不得覆盖已有内容。也可以直接指定从 CI 或 Release 下载的原包：
 
 ```sh
-ruby script/release.rb --artifact pkg/ci/expect-pty-0.2.0.gem
+ruby script/release.rb --rubygems-only --artifact tmp/ci/expect-pty-0.3.0.gem
 ```
 
+将示例路径替换为实际输出的 `Artifact` 路径。`--artifact` 会跳过构建和测试，但仍核对包与当前源码是否一致；需要同时恢复 GitHub Release 时去掉 `--rubygems-only`。
+
 工作流失败时优先使用 Re-run failed jobs，继续使用本次 CI 保存的产物。需要在本地恢复时，检出发布标签对应的干净源码，下载该 Release 的 Gem，再通过 `--artifact` 指定它。
 
 脚本会校验现有 RubyGems 版本和 GitHub Release 附件的 SHA256；一致时复用，不一致时中止。已有 GitHub Release 缺少附件时会补传，已有版本和附件不会被覆盖。

data/docs/VERIFICATION.md

@@ -1,6 +1,70 @@
 # 验证记录
 
-## 当前源码：Ruby 原生接口与关闭策略（2026-09-12）
+## 0.3.0 发布前复核（2026-09-26）
+
+以 0.2.0 为基线导入源码更新，发布前增加 8 项回归，覆盖退出正则切换、同规则跨次匹配、待发送恢复、跨次 CRLF、转义回调内匹配与异常尾部恢复、嵌套写入超时进度。新用例先在修复前失败，再验证修复；仅内部转义处理器的两项测试随职责调整更新调用方式。
+
+macOS arm64、Ruby 4.0.6、Bundler 4.0.17 下执行 `BUNDLER_VERSION=4.0.17 bash script/ci`：225 项测试、903 条断言，0 失败、错误或跳过；RuboCop 检查 42 个文件无违规，对话示例、Gem 构建、隔离安装及 PTY 对话全部通过。连续 1,000 次使用同一输入调用 `interact`，仅保留一个输入包装器，关闭会话不关闭借用 IO。
+
+真实 IO 的已有 Ruby 写缓冲可能让 `write_nonblock` 先阻塞刷新，已在 README 明确首次写入前设置 `sync` 或交接前排空缓冲的要求；未通过绕过缓冲改变字节顺序。真实 SSH 与完整上游差分不在本次验证范围。远端平台矩阵以发布提交对应的 GitHub Actions 结果为准，以下记录属于各自历史时点。
+
+## 转接期限、交付恢复与输入接续（2026-09-26）
+
+继续引用审查中的 R1–R5，在原有未提交改动上修复；基线为 194 项测试 / 737 条断言全部通过。新增 `test/relay_recovery_test.rb` 的前 8 个用例先在未修复实现运行，得到 5 个失败、3 个错误，分别确认阻塞超时、部分发送重放、监听器失败重放、短写入丢后缀、原始输入 IO 接续、背压读取 EINTR、写超时进度和 EOF 截断编码问题。修复后这 8 项通过，再扩展到 23 项恢复与边界用例。
+
+根因与修复：
+
+- `interconnect` 的期限原先只约束读取循环，同步 `target.write` 可以无限阻塞；`Relay` 现统一 select 读写并保留总期限，超时后的前缀刷新也只尝试非阻塞写入。
+- 原先只有单次 `write` 的局部偏移，转发失败后重新发送整个源缓冲；`RelayWriter` 现按目标保留游标，成功目标不重放，短写入继续后缀，flush 异常只重试 flush。转义回调等待前缀交付，剩余输入与待发送数据分别保留。
+- `interact` 原先每次新建输入包装器；现由连接持有并按原始 IO 身份复用，关闭连接时不等键盘 EOF、不关闭借用 IO。关闭路径也先通过有界测试复现等待，再修复并复验。
+- 背压读取的 `EINTR` 纳入原写期限重试；直接写超时异常提供 `bytes_written`。编码检查感知 EOF，固定 UTF-8 正则对截断字符抛出 `EncodingError`，匹配缓冲保留原字节。
+
+同类路径复核覆盖直接写入、转接的常规/转义/EOF/超时发送、日志及普通监听器的 `emit`、匹配和转义两处正则定位。共同 `emit` 同样补齐短写入检查；匹配和转义都传入 EOF 状态。日志、回调、普通匹配的监听器以及自定义写入对象仍同步运行，文档明确这些操作不受 IO 等待期限强制中断；自定义对象必须准确返回已接受的字节数。R6 使用 Ruby 已有的正则实例 timeout，新增测试验证异常透传、缓冲保留及全局配置不变，未增加进程全局设置。
+
+| 环境 | 完整 `script/ci` | 打包及运行 |
+| --- | --- | --- |
+| macOS arm64，Ruby 4.0.7 | 217 项 / 857 断言，0 失败、错误、跳过；RuboCop 42 文件无违规 | 对话示例、Gem 构建、隔离安装及真实 PTY 对话通过 |
+| Linux aarch64，Ruby 3.2.11 | 217 项 / 857 断言，0 失败、错误、跳过；RuboCop 42 文件无违规 | 对话示例、Gem 构建、隔离安装及真实 PTY 对话通过 |
+
+Linux 从 gemspec 文件白名单及锁文件构造独立源码快照，只读挂载后复制到容器，使用 Bundler 4.0.20、锁定依赖及 `BUNDLE_FROZEN=true`；未读取或分发工作区设备日志。检查构建包包含 `relay.rb`、转接写入器（现名 `relay_writer.rb`）、原有重命名模块和新增回归测试，不含 `tmp/` 或 `.git/`。macOS 构建时存在本机 RDoc 多版本重复常量警告，命令成功退出，隔离安装与 PTY 验证通过。工作区原有 16 处样式问题只作相应格式修正。
+
+Linux 首轮新增用例误把 0.1 秒转接超时当作发送完成：`pending_output? == false` 时，`buffer` 仍可能含尚未排入队列的输入。探针证实该状态存在；用例改为关闭源写端并等待转接返回该 EOF 来源，明确验证缓冲已空后再断言回复，避免依赖机器吞吐量。
+
+`git diff --check` 通过。未运行 Ruby 3.3/3.4、远端 CI 或真实 SSH；未提交、推送或发布。新增源码仍需随现有重构文件一起纳入后续提交。性能窗口、完整输出存储等建议已补充使用说明，未改变默认缓冲上限或任意正则的匹配语义。
+
+## Tcl 对照与全项目复核（2026-09-26）
+
+基于 `e6fc883` 及当前全部未提交改动，复核库源码、测试、示例、打包和发布脚本。保留既有 `Matcher`、`SessionResources` 和 `interaction.rb` 职责命名，不新增兼容别名。本轮补充四项回归测试，修复三处问题：
+
+- Ruby 编码转换器识别非法 UTF-8 前缀，避免将过长编码、代理区或越界码点误判为等待更多字节；合法分片继续等待，原字节保留。
+- 转接读取先存入转接缓冲，再调用日志；日志异常后输入归还会话，可继续匹配。
+- 新建日志使用 `0600` 权限；追加和覆盖已有文件均保留其权限。
+
+三项缺陷均先运行回归测试确认旧实现失败，再修改实现并复验。合法分片用例覆盖二、三、四字节字符的每个截断位置。
+
+| 环境 | 完整 `script/ci` | 打包验证 |
+| --- | --- | --- |
+| macOS arm64，Ruby 4.0.7 | 191 项 / 728 断言，0 失败、错误、跳过；RuboCop 39 文件无违规 | 对话示例、构建、隔离安装与真实 PTY 对话通过 |
+| Linux aarch64，Ruby 3.2.11 | 191 项 / 728 断言，0 失败、错误、跳过；RuboCop 39 文件无违规 | 对话示例、构建、隔离安装与真实 PTY 对话通过 |
+
+macOS 验证目录从 `git archive HEAD`、全部工作区补丁及未跟踪源码重建，包含本地开发锁文件；隔离的 GEM_HOME 安装 Bundler 4.0.17，并以 `BUNDLE_FROZEN=true bash script/ci` 验证，未依赖本机损坏的 Bundler 启动器。Linux 使用 `ruby:3.2-bookworm`，源码只读挂载并复制到容器临时目录，同样安装锁定依赖；完整测试包含 `release_test.rb`。
+
+核对 Tcl 官方 `expect.c` 的匹配、缓冲消费和继续计时流程，以及 `exp_inter.c` 的部分模式匹配和终端恢复；另在 Tcl Expect 5.45.4 与本库中分别实跑缓冲消费、保留、EOF 和 wait 场景，均通过。功能差异和未实现能力见 [接口说明](COMPATIBILITY.md#tcl-expect-语义边界)，不代表完整 Tcl 差分验收。
+
+本轮未重跑真实 SSH、Ruby 3.3/3.4 或远端 CI，也未提交、推送或发布。以下记录保留各自验证时点，不作为本轮执行证据。
+
+## 当前工作区：交互、匹配与 IO 修复（2026-09-24）
+
+本轮检查并修复固定 UTF-8 正则在末尾字符未收齐时提前匹配、正则转义历史窗口截断到 UTF-8 续字节，以及就绪查询、写入和转接中的 `EINTR`。新增回归覆盖分片字符、历史窗口和 select/read/write 中断。
+
+| 环境 | 测试结果 | 其他检查 |
+| --- | --- | --- |
+| macOS arm64，Ruby 4.0.7 | 187 项 / 692 断言，无失败、错误、跳过 | RuboCop 39 个文件无违规；对话示例通过 |
+| Linux aarch64，Ruby 4.0.6 | 176 项 / 658 断言，无失败、错误、跳过 | 只读挂载源码；排除依赖本机打包环境的 `release_test.rb` |
+
+`git diff --check` 通过。本轮未在 Ruby 3.2 重新运行完整测试，也未运行远端 CI；下节的 Ruby 3.2 结果属于 2026-09-12 的历史验证，不能代表当前工作区。
+
+## Ruby 原生接口与关闭策略（2026-09-12）
 
 此次重构以 144 项测试 / 526 个断言为基线。原有交互场景全部迁移到新接口，新增 18 项回归，三个环境均通过 `bundle exec rake`（RuboCop 和完整测试）及 `ruby examples/dialogue.rb`：
 

data/expect-pty.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"
   spec.files = Dir[
-    "lib/**/*.rb", "examples/**/*.rb", "examples/**/*.md", "docs/**/*.md",
+    "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"
   ]

data/lib/expect/configuration.rb

@@ -67,42 +67,49 @@ class Expect
     def raw_pty=(value)
       @raw_pty = !!value
     end
+
     alias raw_pty? raw_pty
 
     # 控制匹配成功后是否保留完整缓冲；启用时由继续回调自行消费匹配内容。
     def preserve_buffer=(value)
       @preserve_buffer = !!value
     end
+
     alias preserve_buffer? preserve_buffer
 
     # 控制接收字节是否同步输出到当前 $stdout；默认关闭。
     def log_stdout=(value)
       @log_stdout = !!value
     end
+
     alias log_stdout? log_stdout
 
     # 控制接收字节是否转发给监听器，与 stdout 和日志目标分别管理。
     def log_listeners=(value)
       @log_listeners = !!value
     end
+
     alias log_listeners? log_listeners
 
     # 控制人工转接期间是否自动设置并恢复终端模式。
     def raw_terminal=(value)
       @raw_terminal = !!value
     end
+
     alias raw_terminal? raw_terminal
 
     # 控制收到任何新数据时是否刷新匹配期限，适用于按静默时长判断超时。
     def reset_timeout_on_read=(value)
       @reset_timeout_on_read = !!value
     end
+
     alias reset_timeout_on_read? reset_timeout_on_read
 
     # 控制通用 close 是否先软关闭；最终资源清理仍由硬关闭兜底。
     def graceful_close=(value)
       @graceful_close = !!value
     end
+
     alias graceful_close? graceful_close
 
     # 导出新的属性 Hash，用于构造会话副本或发布下一份默认配置。

data/lib/expect/interaction.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "relay_writer"
+require_relative "relay"
+
+# 为会话补充人工接管和多路 IO 转接；核心会话定义位于 lib/expect.rb。
+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.
+  class InteractOutput
+    def initialize(target)
+      @target = target
+      @previous_carriage_return = false
+    end
+
+    attr_reader :target
+
+    def render(data)
+      bytes = data.to_s.b
+      rendered = bytes.gsub(/(?<!\r)\n/n, "\r\n")
+      rendered = rendered.byteslice(1..) if @previous_carriage_return && bytes.start_with?("\n")
+      @previous_carriage_return = bytes.end_with?("\r")
+      rendered
+    end
+
+    def write(data)
+      @target.write(render(data))
+    end
+  end
+
+  private_constant :InteractOutput
+
+  # 注册字面、正则转义或 :eof 事件；回调用闭包保存上下文，nil/false 停止，其余值继续。
+  def on_sequence(sequence, &block)
+    key = case sequence
+          when :eof, Regexp then sequence
+          when String then sequence.b.freeze
+          else raise ArgumentError, "sequence must be a String, Regexp or :eof"
+          end
+    raise ArgumentError, "escape sequence must not be empty" if key == ""
+
+    @sequences[key] = block
+    self
+  end
+
+  # 临时将输入、会话和输出相连，实现人工接管；结束时恢复双方监听器、日志开关和转义设置。
+  def interact(input: $stdin, escape: nil, output: nil, timeout: nil)
+    source = interact_source(input)
+    output ||= input.equal?($stdin) ? $stdout : input
+    saved_self = [listeners, log_stdout, log_listeners]
+    saved_source = [source.listeners, source.log_stdout, source.log_listeners, source.sequences.dup]
+    terminal_state = prepare_interact_terminal(source)
+    display = interact_display(source, output, terminal_state)
+    # 临时建立“用户输入 -> 子进程 -> 显示输出”的双向连接，原监听关系在 ensure 中恢复。
+    self.listeners = [display]
+    self.log_stdout = false
+    self.log_listeners = true
+    source.listeners = [self]
+    source.log_stdout = false
+    source.log_listeners = true
+    source.on_sequence(escape) if escape
+    Expect.interconnect(self, source, timeout: timeout)
+  ensure
+    begin
+      if saved_self
+        self.listeners, self.log_stdout, self.log_listeners = saved_self
+        source.listeners, source.log_stdout, source.log_listeners, source.sequences = saved_source
+      end
+    ensure
+      restore_interact_terminal(terminal_state)
+    end
+  end
+
+  # 按各会话 listeners 建立转发图，处理转义、EOF 和总期限，返回引发停止的会话或 nil。
+  def self.interconnect(*sessions, timeout: nil)
+    raise ArgumentError, "interconnect requires Expect sessions" if sessions.empty? || sessions.any? do |session|
+      !session.is_a?(Expect)
+    end
+
+    Relay.new(sessions, timeout).run
+  end
+
+  # 超时或异常后仍有未交付的数据；重新 interconnect 同一源会话可继续发送。
+  def pending_output? = @relay_outputs.any? { |output| !output.done? }
+
+  # 转发一个会话的待处理缓冲并剔除转义；返回 false 表示应结束整个转接。
+  # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
+  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)
+      matches = sequences.filter_map do |key, handler|
+        if key.is_a?(Regexp)
+          position = Pattern.new(value: key).locate(history + buffer, final: final)
+          if position
+            offset, length, = position
+            raise ArgumentError, "escape regexp must consume at least one byte" if length.zero?
+
+            # 历史前缀已实时转发，不能撤回；负偏移表示本次只需消费转义尚未转发的部分。
+            [offset - history.bytesize, length, handler]
+          end
+        else
+          position = buffer.index(key)
+          [position, key.bytesize, handler] if position
+        end
+      end
+      if (found = matches.min_by(&:first))
+        position, length, callback = found
+        if position.positive?
+          if block_given?
+            yield buffer.byteslice(0, position)
+            buffer.replace(buffer.byteslice((position + length)..))
+            history.clear
+            # 已确定的转义不能在等待写入后重新匹配；尾部可能在等待期间继续增长。
+            session.__send__(:relay_callback=, [callback])
+            return :pending
+          end
+          session.__send__(:propagate, buffer.byteslice(0, position))
+        end
+        buffer.replace(buffer.byteslice([position + length, 0].max..))
+        # 转义消费后清除历史，防止继续回调再次匹配同一个转义。
+        history.clear
+        return false unless callback&.call
+
+        next
+      end
+
+      # 暂存可能构成字面转义的最长后缀，保证 STOP 分两次读取时 ST 不会提前发给子进程。
+      held = 0
+      unless final
+        sequences.each_key do |key|
+          next if key.is_a?(Regexp)
+
+          [key.bytesize - 1, buffer.bytesize].min.downto(1) do |length|
+            if buffer.end_with?(key.byteslice(0, length))
+              held = [held, length].max
+              break
+            end
+          end
+        end
+      end
+      count = buffer.bytesize - held
+      count = [count, READ_SIZE].min if block_given?
+      if count.positive?
+        data = buffer.byteslice(0, count)
+        block_given? ? yield(data) : session.__send__(:propagate, data)
+      end
+      if sequences.keys.any?(Regexp)
+        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 }
+            # 窗口可能从 UTF-8 续字节开始；丢弃不完整的首字符后再交给固定编码正则。
+            history.slice!(0) while (byte = history.getbyte(0)) && (0x80..0xBF).cover?(byte)
+          end
+        end
+      end
+      buffer.slice!(0, count)
+      return block_given? && count.positive? ? :pending : true
+    end
+  end
+
+  private_class_method :relay_buffer
+
+  def interact_source(input)
+    return input if input.is_a?(Expect)
+
+    @interact_inputs ||= {}.compare_by_identity
+    @interact_inputs.delete_if { |io, session| io.closed? || session.closed? }
+    @interact_inputs[input] ||= Expect.open(input)
+  end
+
+  def queue_output(data)
+    targets = []
+    targets << $stdout if log_stdout?
+    targets.concat(@listeners) if log_listeners?
+    @relay_outputs = targets.map do |target|
+      if target.is_a?(InteractOutput)
+        RelayWriter.new(target.target, target.render(data))
+      else
+        RelayWriter.new(target, data)
+      end
+    end
+  end
+
+  private :interact_source, :queue_output
+
+  # Only interact knows which stream is the local keyboard. Generic interconnect leaves terminals alone.
+  def prepare_interact_terminal(source)
+    return unless source.raw_terminal? && source.tty?
+
+    io = source.to_io
+    state = [io, io.console_mode]
+    io.raw!
+    state
+  rescue Exception # rubocop:disable Lint/RescueException -- Restore a partially changed terminal on interrupts.
+    restore_interact_terminal(state)
+    raise
+  end
+
+  def restore_interact_terminal(state)
+    return unless state
+
+    io, mode = state
+    io.console_mode = mode unless io.closed?
+  end
+
+  def interact_display(source, output, terminal_state)
+    @interact_output = nil unless terminal_state && @interact_output&.target.equal?(output)
+    return output unless terminal_state
+
+    target = output.respond_to?(:to_io) ? output.to_io : output
+    return output unless target.respond_to?(:tty?) && target.tty?
+    return output unless source.to_io.stat.rdev == target.stat.rdev
+
+    # 同一输出的 CRLF 可能跨越两次接管；只缓存最近目标，避免长期持有旧终端。
+    @interact_output ||= InteractOutput.new(output)
+  rescue IOError, SystemCallError
+    output
+  end
+
+  private :prepare_interact_terminal, :restore_interact_terminal, :interact_display
+
+  protected
+
+  # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
+  attr_accessor :sequences
+  # 让同步写入的背压读取遵守当前转接的数据所有权，退出后恢复普通匹配缓冲。
+  attr_accessor :interaction_buffer
+  attr_reader :relay_outputs
+  attr_accessor :relay_callback
+
+  # 历史属于产生它的转义规则；同规则重入继续匹配，换规则不能重放已转发输入。
+  def relay_history
+    sequences = @sequences.except(:eof)
+    @relay_history = "".b unless @relay_history_sequences == sequences
+    @relay_history_sequences = sequences
+    @relay_history
+  end
+
+  # 转接尚未处理的输入不能被匹配窗口上限裁掉；下次 expect 会重新应用该上限。
+  def restore_relay_buffer(buffer)
+    @buffer = buffer + @buffer
+  end
+end