expect-pty 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bffb0687dc259c0b1e2abc3920def8a496c67b0853dda43b0f7da98d0273b8b6
-  data.tar.gz: bd56c190bd1bb312902e2679a03c91d620bff4498551402344a46f979df1d9dd
+  metadata.gz: e860210612e392f800cf5839bb130625bafb17e47ffc86e49787446537c63a81
+  data.tar.gz: cbabed54f7dcd21c2bd5dc7ee2b63627a3ed424f94101df786812ba5e652ab00
 SHA512:
-  metadata.gz: e018796d8f8b2e9b2efdf515bce9ef4b57fd0e5d63e2be511e97231990b0525d98f9814c9aa23a480ae9e0956b28048e70de6187ebb535e91016f5bcb21cee61
-  data.tar.gz: 8633ebbdbee3858cb7a0756160b15357fdbc7eaf3df46ce2d8ac76f0a57eb74c3b35271c05661fd07de1c9d2f011a1e4fc0f839e4279368a7ac15a70b3deaa9e
+  metadata.gz: cb11a81d8cce676da6cc3fc0aaf66044eff142e7e4fb01d8537b4b3d3e77bb691974f28f7a5eebbda260b77def9efaf3b8c5b26956e41ff576cf4aae1b73c24c
+  data.tar.gz: f362101cc8db4d810c9a4ad8c48cf1b4000cd626d9063085421901092edd76d8347b56c2ad44681e4906b6ad77d5f5809fccc5a24bb111cd254fa7e0523266fc

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.5.1 - 2026-09-27
+
+- **终端清理**：`stty` 读取失败或中断后也会清理辅助管道和进程，保留原始异常，避免影响主会话。
+- **脱敏性能**：减少连续与重叠秘密匹配时的内存分配和处理耗时，保留跨块、规则更新和流尾部的脱敏行为。
+
+## 0.5.0 - 2026-09-27
+
+- **独立脱敏**：新增无需创建会话的 `Expect::Redactor`，支持完整文本和分块字节流过滤，以及自定义替换标记。
+- **过滤规则**：支持空模式列表和复制校验后的规则更新，完整文本仅匹配完整秘密，流结束时默认隐藏未完成的秘密前缀，现有会话脱敏行为保持不变。
+
 ## 0.4.0 - 2026-09-27
 
 - **缓冲与生命周期**：新增只读 `buffer_discarded_bytes`，区分上限裁剪与正常消费；补齐外部回收进程、借用 IO、重复关闭和失败重试的契约回归。

data/README.md

@@ -16,7 +16,7 @@ RubyGems/Bundler 解析。推荐入口 **`require "expect/pty"`**；本项目提
 项目和仓库名为 `expect-ruby`，Gem 名为 `expect-pty`。在应用的 Gemfile 中添加以下内容，然后运行 `bundle install`：
 
 ```ruby
-gem "expect-pty", "~> 0.4.0", require: "expect/pty"
+gem "expect-pty", "~> 0.5.1", require: "expect/pty"
 ```
 
 也可直接执行 `gem install expect-pty`。需要跟随开发分支时，可从 GitHub 安装：
@@ -29,8 +29,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.4.0.gem
-gem install ./tmp/expect-pty-0.4.0.gem
+gem build expect-pty.gemspec --output tmp/expect-pty-0.5.1.gem
+gem install ./tmp/expect-pty-0.5.1.gem
 ```
 
 ```ruby
@@ -290,6 +290,23 @@ session.log_to("session.log")
 3 的缓冲快照只显示 `[FILTERED]`，避免部分消费或裁剪后剩下的秘密片段绕过过滤。日志回调的分块边界因此可能变化。GC
 兜底不会调用用户日志回调，需显式关闭会话以交付过滤器尾部。
 
+应用需要过滤自己的日志或错误文本时，可以直接使用独立的字节过滤器，无需打开 PTY 或创建会话：
+
+```ruby
+require "expect/redactor"
+
+safe_message = Expect::Redactor.redact(message, [password], replacement: "[REDACTED]")
+filter = Expect::Redactor.new([password], replacement: "[REDACTED]")
+output.write(filter.append(chunk)) # 每个输出流使用独立实例
+output.write(filter.finish)
+```
+
+`patterns=` 用由非空字符串组成的数组替换后续规则，空数组表示不注册秘密；输入数组、字符串和替换标记都会复制，
+无效更新不改变已有规则或暂存数据。已输出的内容不能撤回，更新后也会保留先前标记为隐藏的尾部区间。
+`redact` 处理完整文本，只匹配完整秘密；`finish` 默认还隐藏未完成的秘密前缀。已确定输入完整的调用方可用
+`finish(partial: false)`。连续或重叠的隐藏区间合并成一个替换标记。过滤不自动识别终端控制符或编码，过滤器本身不持有 IO，
+也不负责会话作用域或异常对象的安全字段选择。该公共接口从 0.5.0 开始提供。
+
 ```ruby
 session.interact(input: $stdin, escape: "\x1d", output: $stdout) # Ctrl-]
 

data/benchmark/redactor.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "support"
+
+# 同一驱动可加载基线或候选库；每轮创建独立过滤器，不能跨样本继承流状态。
+module RedactorBenchmark
+  def self.measure(runner, name, input, patterns, expected, chunk_size: nil, partial: false)
+    chunks = if chunk_size
+               (0...input.bytesize).step(chunk_size).map { |offset| input.byteslice(offset, chunk_size) }
+             else
+               [input]
+             end
+    runner.measure(name, bytes: input.bytesize,
+                         inputs: { bytes: input.bytesize, secret_lengths: patterns.map(&:bytesize),
+                                   chunk_size: chunk_size, partial: partial, repeated_finish: true },
+                         verify: ->(output) { ExpectBenchmark.check(output == expected, "incorrect #{name} output") },
+                         iterations: 5) do
+      filter = Expect::Redactor.new(patterns)
+      output = +"".b
+      chunks.each { |chunk| output << filter.append(chunk) }
+      output << filter.finish(partial: partial) << filter.finish(partial: partial)
+    end
+  end
+end
+
+runner = ExpectBenchmark::Runner.new("redactor")
+size = runner.smoke ? 512 : 65_536
+plain = "x" * size
+RedactorBenchmark.measure(runner, "empty_rules", plain, [], plain)
+RedactorBenchmark.measure(runner, "no_match", plain, ["secret"], plain)
+RedactorBenchmark.measure(runner, "no_match_many", plain, %w[secret password token credential], plain)
+RedactorBenchmark.measure(runner, "sparse", "#{plain}secret!", ["secret"], "#{plain}[FILTERED]!")
+RedactorBenchmark.measure(runner, "contiguous_short", "token" * (size / 5), ["token"], "[FILTERED]")
+
+(runner.smoke ? [1, 32, 128] : [1, 32, 1024, 4096]).each do |length|
+  RedactorBenchmark.measure(runner, "overlap_#{length}", "a" * size, ["a" * length], "[FILTERED]")
+end
+count = runner.smoke ? 8 : 256
+RedactorBenchmark.measure(runner, "contained_patterns", "abcde!" * count,
+                          %w[abc bc ab bcd], "[FILTERED]e!" * count)
+RedactorBenchmark.measure(runner, "binary_overlap", "\0\xffABC\x80!".b * count,
+                          ["\xffABC".b, "ABC\x80".b], "\0[FILTERED]!".b * count, chunk_size: 3)
+RedactorBenchmark.measure(runner, "marker_in_input", "[FILTERED] secret!" * count,
+                          %w[secret FILTERED], "[[FILTERED]] [FILTERED]!" * count)
+
+[1, 7, 4096].each do |chunk_size|
+  RedactorBenchmark.measure(runner, "stream_#{chunk_size}", "prefix secret!\n" * count,
+                            ["secret"], "prefix [FILTERED]!\n" * count, chunk_size: chunk_size)
+end
+[true, false].each do |partial|
+  RedactorBenchmark.measure(runner, "partial_#{partial}", "prefix pass", ["password"],
+                            partial ? "prefix [FILTERED]" : "prefix pass", chunk_size: 1, partial: partial)
+end
+
+runner.measure("update_pending", bytes: 10, inputs: { update: "keep old mask and match new secret" },
+                                 verify: lambda { |output|
+                                   ExpectBenchmark.check(output == "[FILTERED]!")
+                                 }, iterations: 100) do
+  filter = Expect::Redactor.new(%w[abc long-pattern])
+  output = filter.append("abcsec")
+  filter.patterns = ["secret"]
+  output << filter.append("ret!") << filter.finish << filter.finish
+end
+runner.finish

data/docs/INTERNAL_CONTRACTS.md

@@ -15,9 +15,9 @@
 | `terminal.rb`                                   | `stty` 和窗口尺寸的会话终端接口                    |
 | `interaction.rb`、`relay.rb`、`relay_writer.rb` | 人工接管、转义处理、共同调度和各目标发送游标       |
 
-`redactor.rb` 为日志和各方向诊断提供内部字节流过滤器，不持有 IO，也不接管协议缓冲。
+`redactor.rb` 提供公共 `Expect::Redactor` 字节过滤接口，供会话日志、各方向诊断及上层库共用，不持有 IO，也不接管协议缓冲。
 
-这些能力文件延续 `interaction.rb` 的类重开方式，公共入口仍是 `expect/pty`。按职责组织方法，不引入新的继承层级，也不复制会话状态。
+会话能力文件延续 `interaction.rb` 的类重开方式，入口为 `expect/pty`；独立过滤器可通过 `expect/redactor` 加载。按职责组织方法，不引入新的继承层级，也不复制会话状态。
 
 跨对象调用使用 `__send__` 访问受保护或私有方法。变更以下入口时，应同时检查调用方与失败恢复路径：
 
@@ -61,6 +61,16 @@ exec 成功后诊断输出失败，也要立即回收未交付给调用方的子
 是否保留原始异常由当前构造、块或关闭作用域显式记录，不能直接读取调用者 rescue 中的 `$!`。`Interrupt` 和 `SystemExit`
 同样先清理再传播；`break` / `throw` 不是异常，此时清理失败仍应抛出。
 
+`stty` 为辅助管道和 PID 创建独立的 SessionResources，不写入主会话的 PID/status，不关闭主会话。
+账本构造被中断时仍关闭局部变量中已经创建的管道；fork 后的副本只关闭本地管道，不向父进程的辅助 PID 发信号或 detach，等待途中也重新核对归属。
+正常路径读取输出并阻塞回收，EINTR 只重试 wait，不再次启动命令，也不增加固定等待。
+异常路径先尝试关闭两个管道，再依次等待自然退出、发送 TERM、发送 KILL；每阶段使用固定的 50ms 单调时钟预算，
+非阻塞 wait 或 signal 的 EINTR 不延长期限。ECHILD 立即释放该 PID 的归属，不向可能复用的 PID 发信号；
+ESRCH 后仍尝试回收。三个阶段结束或系统调用失败后仍有 PID 时交给 `Process.detach` 异步回收，不保证返回前退出，
+也不伪造退出状态。预算约束进程轮询，不是任意同步 IO 或系统调度的硬实时保证。
+本次主异常（包括 Interrupt/SystemExit）保持对象身份；没有主异常时传播首个 IOError/SystemCallError 清理失败。
+永久失败的 close 只保证被尝试，不能报告成句柄已关闭；缺失 stty 仍为 IOError 并保留 ENOENT cause。
+
 ## 缓冲裁剪与字面扫描
 
 `buffer_discarded_bytes` 随会话累计，只在匹配窗口执行 `trim_buffer` 时增加。读取、`buffer=`、降低上限和下一次匹配应用上限都可能触发裁剪；匹配消费、清空、EOF 和 Relay 交接不计入，关闭后仍保留计数。它是可观察的丢弃量，不是缓冲满事件，也不提供全文归档。
@@ -77,7 +87,13 @@ exec 成功后诊断输出失败，也要立即回收未交付给调用方的子
 
 `logging.rb` 分开处理接收日志、诊断和协议转发。`diagnostic_output` 借用 Logger、可写对象或回调，不进入资源账本；默认沿用 stderr。回调接收冻结的事件 Hash 和 message 字符串，不含会话对象。诊断失败与其他同步 IO 错误同样保留已读取的原始输入。
 
-`redactor.rb` 是内部的字节流过滤器。会话复制并追加注册秘密，每个接收日志流以及发送、接收诊断方向各自持有过滤器。暂存最长秘密长度减一的尾部，重叠秘密合并为隐藏区间，过滤发生在 `inspect` 转义之前。缓冲快照可能只剩秘密中间字节，启用脱敏时整体隐藏，不重复展示其内容。
+`redactor.rb` 是无 IO 的公共字节过滤器。会话复制并追加注册秘密，每个接收日志流以及发送、接收诊断方向各自持有过滤器。暂存最长秘密长度减一的尾部，重叠秘密合并为隐藏区间，过滤发生在 `inspect` 转义之前。缓冲快照可能只剩秘密中间字节，启用脱敏时整体隐藏，不重复展示其内容。
+
+公共构造器及 `patterns=` 会校验并复制秘密；空模式列表直接交付字节，更新规则不清除已经建立的掩码。
+同一模式的命中按字节偏移递增枚举，相交或相邻区间合并后才写入掩码；不能通过跳过整个秘密长度省略重叠命中。
+合并仍与现有掩码取并集，保留其他模式和旧规则已标记的隐藏字节，不改变跨块连续区间只输出一个替换标记的规则。
+默认替换标记为 `[FILTERED]`，上层库可显式指定自己的标记。类方法 `redact` 使用独立流并以 `finish(partial: false)` 结束完整文本；
+`append`/`finish` 的默认流策略仍隐藏末尾疑似秘密前缀。作用域所有权、终端渲染和异常字段选择由调用方负责。
 
 EOF 结束接收流，日志或诊断目标替换先冲刷旧流，显式关闭结束所有方向；尾部疑似秘密前缀保守隐藏。GC 只清理所属资源，不执行用户回调或过滤尾部输出。调用方需显式关闭以交付尾部；借用日志和诊断目标不关闭，库打开的日志文件仍由 SessionResources 管理。
 
@@ -95,10 +111,12 @@ EOF 结束接收流，日志或诊断目标替换先冲刷旧流，显式关闭
 
 | 不变量 | 测试 |
 | --- | --- |
+| stty 主错误优先、辅助进程回收、EINTR 预算、ECHILD/ESRCH、detach 和主会话隔离 | terminal_cleanup_test |
 | 裁剪计数、正常消费、转接交接与日志错误 | buffer_accounting_test |
 | 外部回收、借用 IO、关闭失败重试、原生错误分类 | lifecycle_contract_test |
 | 绝对期限、接收和回调重置、过期文本、EOF、EINTR、零轮询 | deadline_test |
 | Logger/IO/回调、分片与重叠秘密、二进制、流尾部、关闭失败、覆盖与重入 | diagnostics_test |
+| 公共过滤器独立加载、完整文本与分块、空规则、规则更新、输入复制、安全摘要及固定种子字节区间差分 | redactor_test |
 | 字面跨读取命中、声明优先级、缓存失效、操作序列与全量扫描对照 | literal_scan_test |
 
 ## 既有回归入口

data/docs/PERFORMANCE.md

@@ -7,9 +7,10 @@ bundle exec ruby benchmark/matching.rb
 bundle exec ruby benchmark/relay.rb
 bundle exec ruby benchmark/send_slow.rb
 bundle exec ruby benchmark/scaling.rb
+bundle exec ruby benchmark/redactor.rb
 ```
 
-默认预热一次、采样五次。结果分别写入 `tmp/benchmark/matching.json`、`relay.json`、`send_slow.json`
+默认预热一次、采样五次。结果分别写入 `tmp/benchmark/matching.json`、`relay.json`、`send_slow.json`、`scaling.json`、`redactor.json`
 ，该目录不提交。每个场景先核对非空输入的预期结果，再计时；每轮计时后再次核对最后一次执行的结果。输出包括
 Ruby、平台、源码提交、工作区是否修改、库源码 SHA-256、输入规模、迭代次数、处理字节数、墙钟耗时、分配对象数和 GC 次数。
 
@@ -20,6 +21,7 @@ Ruby、平台、源码提交、工作区是否修改、库源码 SHA-256、输
 | matching  | 4 KiB、64 KiB、1 MiB；1、8、32 个正则；首个命中、末个命中、全未命中；UTF-8 前缀和可选捕获；1、8、32 个会话、多组重复来源和同时就绪的真实管道 |
 | relay     | 无转义、字面转义、16 个正则转义；正常目标与每次只接受 17 字节的目标共同接收相同数据                                                          |
 | send_slow | 真实本地 socket；无回显、持续回显；零延迟和每字符 1ms 延迟                                                                                   |
+| redactor | 空规则、无命中/稀疏/连续/高重叠；包含关系、多秘密、二进制、原文替换标记、1/7/4096 字节分块、partial finish、重复 finish 及 pending 中更新规则 |
 
 `matching` 的扫描用内部 `find_match` 单独度量缓冲扫描，排除 PTY 启动和回调开销；就绪场景包含管道写入、选择和读取。`relay`
 的前三项单独度量转义扫描，混合目标项运行完整转接循环。短写模拟目标吞吐受限，不等同于真实慢网络。`send_slow` 包含
@@ -34,6 +36,10 @@ socket、接收线程和完整回显校验的成本；无回显时计时止于
 
 每个样本记录计时区间前后的 RSS 和打开描述符数，以及进程的描述符上限；采样自身不进入计时或分配计数。RSS 是端点快照，受 Ruby 堆和分配器保留影响，不代表峰值或存活对象大小。平台不支持某项采样时记录 `null`。描述符快照也不是长期泄漏证明，应同时检查重复样本和关闭流程。
 
+`redactor` 每次操作创建独立过滤器，分块数据在计时前准备，计时包含过滤器构造、append 和两次 finish。
+主要输入规模为 64 KiB，高重叠秘密长度为 1/32/1024/4096 字节；smoke 缩小为 512 字节及 1/32/128 字节秘密。
+公共 Runner 会加载完整 Expect（含 PTY）；基准本身不启动 PTY 会话，独立 `require "expect/redactor"` 的无 PTY 契约由测试验证。
+
 ## 同环境对照
 
 对照目录必须包含已知提交的完整源码。两个版本使用同一套基准脚本、同一 Ruby 和依赖，在机器空闲时交替运行，比较原始样本的中位数与分配量：
@@ -72,6 +78,7 @@ bundle exec ruby benchmark/matching.rb --smoke
 bundle exec ruby benchmark/relay.rb --smoke
 bundle exec ruby benchmark/send_slow.rb --smoke
 bundle exec ruby benchmark/scaling.rb --smoke
+bundle exec ruby benchmark/redactor.rb --smoke
 ```
 
 `script/ci` 运行这些小规模正确性检查，不设置墙钟性能阈值。热点优化必须有实际收益证据；减少对象分配不代表所有输入都会变快，也不能替代完整测试和安装验证。
@@ -104,3 +111,55 @@ bundle exec ruby benchmark/scaling.rb --samples 3 --iterations 10
 同一工作树的三次容量样本中，1、16、64 来源各执行十轮的耗时中位数分别为 0.179、1.372、8.285 ms；1,000 来源执行三轮为 401.878 ms。1,000 来源样本的描述符数均为 2,007 → 2,007，RSS 端点从约 35.8 MB 增至 37.9 MB，不能解释为稳定内存上限。阻塞目标场景十轮共 0.186 ms，其他来源仍可推进，描述符数均为 13 → 13。
 
 原始记录为 `tmp/core-improvements/scaling-final.json` 和 `scaling-1000-final.json`，库源码摘要与上述工作树匹配记录一致。当前证据支持保留既有 select 调度，先量化真实负载，再决定是否需要替换后端。
+
+## Redactor 重叠区间合并验证（2026-09-27）
+
+基线为 `v0.5.0` / `b7cd25e736acbfcb43e412ec4d233f9b2602cb03` 的源码归档。使用同一份
+`benchmark/redactor.rb`、macOS arm64、Ruby 4.0.6、Bundler 4.0.17 和相同依赖，按“基线 → 候选”交替运行两轮，
+每轮 `--samples 5 --iterations 20`。下表是最后一轮五个样本的中位数，耗时和分配均为 **20 次操作总量**。
+每项输出在预热及各样本结束后校验，性能采样期间没有并行运行项目测试。
+
+| 工作负载 | 基线 ms | 候选 ms | 基线分配对象 | 候选分配对象 |
+| --- | ---: | ---: | ---: | ---: |
+| 空规则 | 0.438 | 0.416 | 541 | 541 |
+| 单秘密无命中 | 0.774 | 0.973 | 561 | 561 |
+| 多秘密无命中 | 2.305 | 1.447 | 641 | 641 |
+| 稀疏命中 | 1.145 | 1.175 | 581 | 581 |
+| 连续短秘密 | 26.159 | 9.345 | 262,661 | 541 |
+| 重叠 / 1 字节秘密 | 113.787 | 42.799 | 1,311,241 | 541 |
+| 重叠 / 32 字节秘密 | 189.706 | 97.756 | 1,310,661 | 581 |
+| 重叠 / 1024 字节秘密 | 642.376 | 429.316 | 1,290,821 | 581 |
+| 重叠 / 4096 字节秘密 | 1698.130 | 1361.663 | 1,229,381 | 581 |
+| 包含关系 | 2.881 | 2.915 | 26,201 | 26,201 |
+| 二进制跨块重叠 | 7.967 | 8.299 | 101,221 | 101,221 |
+| 原文包含替换标记 | 2.758 | 2.837 | 21,081 | 21,081 |
+| 1 字节分块 | 34.612 | 34.151 | 589,161 | 589,161 |
+| 7 字节分块 | 6.746 | 6.716 | 93,361 | 93,361 |
+| 4096 字节分块 | 1.434 | 1.456 | 10,781 | 10,781 |
+| partial finish | 0.128 | 0.129 | 2,141 | 2,141 |
+| exact finish | 0.117 | 0.113 | 2,021 | 2,021 |
+| pending 中更新规则 | 0.075 | 0.076 | 961 | 961 |
+
+两轮中连续短秘密耗时减少 63.6%–64.3%；重叠秘密按长度分别减少 62.4%–62.8%、48.5%–48.9%、
+33.1%–33.2%、19.7%–19.8%。重叠查找仍逐字节进行，只减少重复掩码分配/覆盖，没有跳过重叠命中或改变脱敏范围。
+
+短样本中的无命中结果波动明显，因此又通过本地 `tmp/guide-review/redactor-common.rb` 筛选同一驱动的常见负载，
+每轮改为 `--samples 5 --iterations 500`，再交替运行两轮。该包装器只跳过上述五项密集命中，不改变任何输入、过滤或校验逻辑。
+第二轮中单秘密无命中为 23.883 → 24.009 ms，多秘密为 56.148 → 56.081 ms，1 字节分块为 873.397 → 870.462 ms。
+存在小幅代价：稀疏命中两轮慢 2.3%/4.5%，4096 字节分块慢 2.2%/2.5%，规则更新慢 1.0%/6.0%；
+后者第二轮 500 次操作为 1.562 → 1.655 ms。其余常见负载约在 -2.8% 至 +3.6% 之间，分配量不变。
+保留此优化的取舍是以少量区间记录计算换取密集/重叠场景的显著分配下降，不声称所有负载都更快，也不设置 CI 墙钟阈值。
+
+复现全负载：
+
+```sh
+bundle exec ruby benchmark/redactor.rb --library /path/to/v0.5.0/lib --samples 5 --iterations 20 --output tmp/benchmark/redactor-before.json
+bundle exec ruby benchmark/redactor.rb --samples 5 --iterations 20 --output tmp/benchmark/redactor-after.json
+```
+
+原始样本：`tmp/guide-review/redactor-before-{4,5}.json`、`redactor-after-{4,5}.json`；
+延长采样：`redactor-common-before-{1,2}.json`、`redactor-common-after-{1,2}.json`。均在忽略目录，不随 Gem 分发。
+基线库 SHA-256 为 `d2a55eb1aa1d00658195f21f32adf37cf3ab8a24bb6a5bcf9564f6e9a6047b28`，
+性能采样时的候选库（版本号仍为 `0.5.0`）为 `753d403cf4801900cb53be5c34b04da0ffa313f25b4d2fb23a6d25ffce36e75a`，
+驱动文件为 `f99f6c8f1ec21d4d97c984dbfd51fd3e17b64fa7968095323e16d68d4a0d4cc0`。
+这些是合成字节过滤负载，不代表完整设备会话吞吐；RSS 端点不用于声称峰值内存降低。

data/docs/VERIFICATION.md

@@ -1,5 +1,13 @@
 # 验证记录
 
+## 0.5.0 公共字节过滤器发布前复核（2026-09-27）
+
+基线为已发布的 `5a219f7`（0.4.0）。本轮公开 `Expect::Redactor`，新增 11 项回归，覆盖独立加载不引入 PTY、完整文本与流尾部策略、跨分片与重叠秘密、自定义替换标记、空规则、输入复制、无效更新原子性及安全摘要；现有会话日志与诊断继续复用该过滤器。
+
+从基线建立独立检出，仅带入本轮改动。macOS arm64、Ruby 4.0.6、Bundler 4.0.17 下执行 `ruby script/release.rb --dry-run`，330 项测试、1,894 条断言全部通过，无失败、错误或跳过；RuboCop 检查 59 个文件无违规。四组基准 smoke、Gem 构建、普通 RubyGems 与最小 Bundler 应用的隔离安装均通过，安装后实际调用公共完整文本和分块过滤接口。
+
+此处记录本地发布预演；远端 Linux/macOS 与 Ruby 3.2/3.3/3.4/4.0 矩阵、标签及下载包校验，以 0.5.0 发布提交对应的 GitHub Actions 与 Release 为准。
+
 ## 0.4.0 发布前复核（2026-09-27）
 
 发布前新增七项回归：总期限在文本回调后到达时，已知 EOF 先于剩余活跃来源的超时派发；覆盖日志路径前交付旧尾部，冲刷失败不能提前截断新文件；嵌套诊断等待保留外层匹配结果；日志回调轮换目标时正确交接所有权；诊断回调新建或再次写入另一方向时，尾部仍交给旧目标。各项均先复现失败，再验证修复，纯相对超时行为保持不变。

data/lib/expect/redactor.rb

@@ -3,10 +3,21 @@
 class Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
-  # 上层负责传入已复制的非空二进制秘密，每个日志目标或诊断方向使用独立实例。
+  # 不依赖会话或 IO；每个日志目标或诊断方向使用独立实例。
   class Redactor
+    # 完整诊断文本只匹配完整秘密；流边界的疑似秘密前缀由 finish 的默认策略保护。
+    def self.redact(data, patterns, replacement: "[FILTERED]")
+      filter = new(patterns, replacement: replacement)
+      filter.append(data) + filter.finish(partial: false)
+    end
+
     # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
-    def initialize(patterns)
+    def initialize(patterns, replacement: "[FILTERED]")
+      unless replacement.is_a?(String) && !replacement.empty?
+        raise ArgumentError, "replacement must be a nonempty String"
+      end
+
+      @replacement = replacement.b.freeze
       self.patterns = patterns
       @pending = "".b
       @hidden = "".b
@@ -15,21 +26,42 @@ class Expect
 
     # 更新后续匹配规则并保留已有尾部与掩码；不能追溯修改已经交付给日志目标的内容。
     def patterns=(patterns)
-      @patterns = patterns
-      @lookbehind = patterns.map(&:bytesize).max - 1
+      unless patterns.is_a?(Array) && patterns.all? { |pattern| pattern.is_a?(String) && !pattern.empty? }
+        raise ArgumentError, "patterns must be an Array of nonempty Strings"
+      end
+
+      @patterns = patterns.map { |pattern| pattern.b.freeze }.uniq.freeze
+      @lookbehind = [(@patterns.map(&:bytesize).max || 0) - 1, 0].max
     end
 
     # 追加一个原始字节块，返回已经可以确定的安全前缀；新秘密可能跨越此前保留的尾部。
     def append(data)
-      @pending << data
+      raise ArgumentError, "data must be a String" unless data.is_a?(String)
+
+      @pending << data.b
       @hidden << ("\0" * data.bytesize)
       mark_secrets
       release([@pending.bytesize - @lookbehind, 0].max)
     end
 
     # EOF、日志目标替换及关闭是流边界；尾部疑似秘密前缀也遮盖，不能因 flush 泄露片段。
-    def finish
+    def finish(partial: true)
+      raise ArgumentError, "partial must be true or false" unless [true, false].include?(partial)
+
       mark_secrets
+      mark_partial_secrets if partial
+      output = release(@pending.bytesize)
+      @masking = false
+      output
+    end
+
+    # 过滤器公开后仍不在诊断摘要中展开注册秘密或尚未交付的原始字节。
+    def inspect = "#<#{self.class}>"
+
+    private
+
+    # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
+    def mark_partial_secrets
       @patterns.each do |pattern|
         [pattern.bytesize - 1, @pending.bytesize].min.downto(1) do |length|
           next unless @pending.end_with?(pattern.byteslice(0, length))
@@ -38,25 +70,31 @@ class Expect
           break
         end
       end
-      output = release(@pending.bytesize)
-      @masking = false
-      output
     end
 
-    private
-
-    # 每次只将命中区域标为隐藏，不清除旧掩码；偏移逐字节推进以识别相互重叠的秘密。
+    # 仍逐字节推进重叠命中，但同一模式的相交/相邻区间只写一次掩码。
+    # 只向旧掩码取并集，不能清除其他模式或旧规则已经隐藏的 pending 字节。
     def mark_secrets
       @patterns.each do |pattern|
-        offset = -1
+        starting = @pending.index(pattern)
+        next unless starting
+
+        length = pattern.bytesize
+        ending = starting + length
+        offset = starting
         while (offset = @pending.index(pattern, offset + 1))
-          @hidden[offset, pattern.bytesize] = "\1" * pattern.bytesize
+          if offset > ending
+            @hidden[starting, ending - starting] = "\1" * (ending - starting)
+            starting = offset
+          end
+          ending = offset + length
         end
+        @hidden[starting, ending - starting] = "\1" * (ending - starting)
       end
     end
 
     # 按连续区间输出，避免逐字节构造字符串；只保存尚可能与下一块组成秘密的后缀。
-    # masking 跨 append 保留，使被分成多个块的同一隐藏区间只输出一次 [FILTERED]。
+    # masking 跨 append 保留，使被分成多个块的同一隐藏区间只输出一次替换标记。
     def release(length)
       output = "".b
       cursor = 0
@@ -64,7 +102,7 @@ class Expect
         hidden = @hidden.getbyte(cursor) == 1
         ending = [@hidden.index(hidden ? "\0" : "\1", cursor) || length, length].min
         if hidden
-          output << "[FILTERED]" unless @masking
+          output << @replacement unless @masking
         else
           output << @pending.byteslice(cursor, ending - cursor)
         end
@@ -76,6 +114,4 @@ class Expect
       output
     end
   end
-
-  private_constant :Redactor
 end

data/lib/expect/terminal.rb

@@ -5,25 +5,30 @@ require "shellwords"
 # 会话终端的模式和窗口尺寸接口；人工接管期间的临时恢复由 interaction.rb 负责。
 class Expect
   # 查询可恢复的终端模式字符串，或通过系统 stty 设置模式；参数按数组传递，不经 shell。
-  # 非终端返回空字符串；命令不存在或执行失败抛出 IOError，管道在所有退出路径关闭。
+  # 辅助进程与管道独立记账，不能覆盖主会话 PID；失败时保留原异常并有界回收。
   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)
+    resources = SessionResources.new(reader, writer: sink, own: true)
+    resources.pid = Process.spawn("stty", *modes, in: to_io, out: sink, err: sink)
     sink.close
     output = reader.read
-    _, status = Process.waitpid2(child)
+    status = wait_stty(resources.pid)
+    resources.pid = nil
     raise IOError, "stty failed: #{output.strip}" unless status.success?
 
     output.strip
   rescue Errno::ENOENT
+    failed = true
     raise IOError, "stty executable not found in PATH; install the system terminal utilities"
+  rescue Exception # rubocop:disable Lint/RescueException -- 中断同样先回收辅助进程，再原样传播；不读取调用者的旧 $!。
+    failed = true
+    raise
   ensure
-    reader&.close unless reader&.closed?
-    sink&.close unless sink&.closed?
+    cleanup_preserving_failure(failed) { cleanup_stty(resources, reader, sink) }
   end
 
   # 读取终端的 [行数, 列数]；底层并非终端或句柄已关闭时保留原生 IO 异常。
@@ -33,4 +38,65 @@ class Expect
   def winsize=(size)
     to_io.winsize = size
   end
+
+  private
+
+  # 正常路径阻塞取得真实状态，不额外轮询或固定等待；EINTR 不重新执行 stty。
+  def wait_stty(pid)
+    Process.waitpid2(pid).last
+  rescue Errno::EINTR
+    retry
+  end
+
+  # 即使账本初始化被中断，局部变量中的管道仍须关闭；单端失败不跳过其他清理。
+  # 无主异常时由调用方传播首个常规清理错误。
+  def cleanup_stty(resources, reader, sink)
+    failure = nil
+    [reader, sink].compact.each do |io|
+      io.close unless io.closed?
+    rescue IOError, SystemCallError => error
+      failure ||= error
+    end
+    begin
+      reap_stty(resources) if resources
+    rescue IOError, SystemCallError => error
+      failure ||= error
+    end
+    raise failure if failure
+  end
+
+  # 每阶段共享固定的 50ms 单调时钟预算：自然退出、TERM、KILL；中断不续期。
+  # 仍无法同步回收或系统调用失败时交给 detach 的后台 wait，不伪造退出状态。
+  def reap_stty(resources)
+    return unless resources.owner == Process.pid
+
+    [nil, "TERM", "KILL"].each do |signal|
+      deadline = Expect.monotonic + 0.05
+      loop do
+        begin
+          resources.reap
+          return resources.status unless resources.pid && resources.owner == Process.pid
+
+          if signal
+            begin
+              Process.kill(signal, resources.pid)
+            rescue Errno::ESRCH
+              # 退出可发生在非阻塞 wait 与信号之间，仍需继续 wait。
+              nil
+            end
+            signal = nil
+          end
+        rescue Errno::EINTR
+          # 重试沿用本阶段期限，连续 EINTR 也必须交还控制权。
+          nil
+        end
+        remaining = deadline - Expect.monotonic
+        break unless remaining.positive?
+
+        sleep [remaining, 0.005].min
+      end
+    end
+  ensure
+    Process.detach(resources.pid) if resources.pid && resources.owner == Process.pid
+  end
 end

data/lib/expect/version.rb

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

data/script/ci

@@ -7,7 +7,7 @@ bundle exec rake
 bundle exec ruby examples/dialogue.rb
 
 # 只检查小规模工作负载的正确性，不为共享 CI 机器设置性能阈值。
-for benchmark in matching relay send_slow scaling; do
+for benchmark in matching relay send_slow scaling redactor; do
   bundle exec ruby "benchmark/${benchmark}.rb" --smoke
 done
 
@@ -60,7 +60,11 @@ child = 'STDOUT.sync = true; puts "ready"; puts "reply:#{$stdin.gets&.strip}"'
 Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, raw_pty: true, log_stdout: false) do |session|
   session.winsize = [30, 100]
   abort "io-console terminal size failed" unless session.winsize == [30, 100]
+  # BSD stty 设置模式会清空待读输出，先收取提示，使子进程停在等待输入的位置。
   abort "installed gem did not receive the PTY prompt" unless session.expect("ready", timeout: 5)
+  mode = session.stty
+  abort "installed stty query failed" if mode.empty?
+  session.stty(mode)
 
   session.puts("expect-ruby")
   abort "installed gem PTY dialogue failed" unless session.expect("reply:expect-ruby", timeout: 5)
@@ -68,7 +72,11 @@ Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", child, raw_pty: true, log_st
   abort "installed gem child did not exit successfully" unless status&.success?
 end
 
-# 使用已安装包验证内部过滤器随包分发，且结构化诊断无需加载可选的 Logger。
+# 使用已安装包验证公共过滤器随包分发，且结构化诊断无需加载可选的 Logger。
+filter = Expect::Redactor.new(["secret"], replacement: "[REDACTED]")
+filtered = filter.append("sec") + filter.append("ret!") + filter.finish
+abort "installed public redactor failed" unless filtered == "[REDACTED]!"
+abort "installed complete-text redactor failed" unless Expect::Redactor.redact("sec", ["secret"]) == "sec"
 reader, producer = IO.pipe
 events = []
 transcript = StringIO.new

data/test/redactor_test.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "open3"
+require "rbconfig"
+require_relative "../lib/expect/redactor"
+
+class RedactorTest < Minitest::Test
+  def test_standalone_require_does_not_load_pty_or_allocate_a_session
+    program = <<~RUBY
+      require "expect/redactor"
+      abort "PTY loaded" if defined?(PTY)
+      abort "unexpected result" unless Expect::Redactor.redact("secret!", ["secret"]) == "[FILTERED]!"
+    RUBY
+    output, status = Open3.capture2e(RbConfig.ruby, "--disable-gems", "-I", File.expand_path("../lib", __dir__),
+                                     "-e", program)
+    assert status.success?, output
+  end
+
+  def test_empty_patterns_pass_binary_input_without_buffering
+    filter = Expect::Redactor.new([])
+    assert_equal "\xff\0raw".b, filter.append("\xff\0raw".b)
+    assert_empty filter.finish
+    assert_equal "plain", Expect::Redactor.redact("plain", [])
+  end
+
+  def test_one_shot_redaction_does_not_treat_an_ordinary_suffix_as_a_secret_prefix
+    assert_equal "pass", Expect::Redactor.redact("pass", ["password"])
+    assert_equal "[REDACTED]!", Expect::Redactor.redact("password!", ["password"], replacement: "[REDACTED]")
+  end
+
+  def test_stream_finish_masks_partial_secrets_by_default
+    filter = Expect::Redactor.new(["password"])
+    assert_equal "prefix [FILTERED]", filter.append("prefix pass") + filter.finish
+    assert_empty filter.finish
+    assert_equal "[FILTERED]!", filter.append("password!") + filter.finish
+  end
+
+  def test_exact_finish_is_explicit_and_validated
+    filter = Expect::Redactor.new(["password"])
+    filter.append("pass")
+    assert_raises(ArgumentError) { filter.finish(partial: nil) }
+    assert_equal "pass", filter.finish(partial: false)
+  end
+
+  def test_custom_marker_and_overlapping_patterns_at_every_boundary
+    patterns = ["alpha[REDACTED]omega", "[REDACTED]", "REDACTED", "[", "abc", "cde"]
+    input = "alpha[REDACTED]omega | [REDACTED] | abcde!"
+    expected = "[REDACTED] | [REDACTED] | [REDACTED]!"
+    (0..input.bytesize).each do |split|
+      filter = Expect::Redactor.new(patterns, replacement: "[REDACTED]")
+      actual = filter.append(input.byteslice(0, split)) + filter.append(input.byteslice(split..)) + filter.finish
+      assert_equal expected, actual, "split #{split}"
+    end
+    filter = Expect::Redactor.new(patterns, replacement: "[REDACTED]")
+    actual = input.bytes.map { |byte| filter.append(byte.chr) }.join + filter.finish
+    assert_equal expected, actual
+    assert_equal expected, Expect::Redactor.redact(input, patterns, replacement: "[REDACTED]")
+  end
+
+  def test_patterns_and_replacement_are_copied
+    secret = +"secret"
+    patterns = [secret]
+    replacement = +"hidden"
+    filter = Expect::Redactor.new(patterns, replacement: replacement)
+    secret.replace("public")
+    patterns.clear
+    replacement.clear
+    assert_equal "hidden!", filter.append("secret!") + filter.finish
+  end
+
+  def test_invalid_pattern_update_is_atomic_and_preserves_pending_data
+    filter = Expect::Redactor.new(["secret"])
+    filter.append("sec")
+    [nil, "secret", [""], ["valid", 1]].each do |patterns|
+      assert_raises(ArgumentError) { filter.patterns = patterns }
+    end
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+  end
+
+  def test_pattern_update_keeps_hidden_spans_and_matches_new_secret_across_chunks
+    filter = Expect::Redactor.new(%w[abc long-pattern])
+    filter.append("abcsec")
+    filter.patterns = ["secret"]
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+    filter.patterns = []
+    assert_equal "secret", filter.append("secret")
+    assert_empty filter.finish
+  end
+
+  def test_invalid_input_and_replacement_do_not_mutate_stream
+    [nil, "", 3].each do |replacement|
+      assert_raises(ArgumentError) { Expect::Redactor.new([], replacement: replacement) }
+    end
+    filter = Expect::Redactor.new(["secret"])
+    filter.append("sec")
+    assert_raises(ArgumentError) { filter.append(nil) }
+    assert_equal "[FILTERED]!", filter.append("ret!") + filter.finish
+  end
+
+  def test_inspect_does_not_expose_registered_or_pending_bytes
+    filter = Expect::Redactor.new(["private-pattern"])
+    filter.append("raw-pending")
+    assert_equal "#<Expect::Redactor>", filter.inspect
+  end
+
+  def test_seeded_binary_chunks_match_a_naive_union_of_full_and_partial_spans
+    random = Random.new(5000)
+    250.times do |index|
+      alphabet = index.even? ? [97, 98] : [0, 97, 98, 99, 128, 255]
+      input = Array.new(random.rand(0..120)) { alphabet.sample(random: random) }.pack("C*")
+      patterns = Array.new(random.rand(0..6)) do
+        Array.new(random.rand(1..8)) { alphabet.sample(random: random) }.pack("C*")
+      end
+      chunks = []
+      offset = 0
+      while offset < input.bytesize
+        chunks << input.byteslice(offset, random.rand(1..15))
+        offset += chunks.last.bytesize
+      end
+      [false, true].each do |partial|
+        expected = reference_redact(input, patterns, partial: partial)
+        [[input], input.bytes.map(&:chr), chunks].each_with_index do |partition, kind|
+          filter = Expect::Redactor.new(patterns)
+          actual = partition.map { |chunk| filter.append(chunk) }.join.b + filter.finish(partial: partial)
+          assert_equal expected, actual, "seed=5000 case=#{index} partition=#{kind} partial=#{partial}"
+          assert_empty filter.finish(partial: partial)
+        end
+      end
+    end
+  end
+
+  def test_long_overlaps_merge_across_chunks_without_repeating_markers
+    filter = Expect::Redactor.new(["a" * 1024, "a" * 32, "ab"])
+    output = +""
+    256.times { output << filter.append("a" * 17) }
+    output << filter.append("b!") << filter.finish
+    assert_equal "[FILTERED]!", output
+  end
+
+  def test_rule_removal_keeps_hidden_pending_bytes_and_partial_finish_is_separate
+    filter = Expect::Redactor.new(%w[aaaa long-pattern])
+    assert_empty filter.append("aaaaa")
+    filter.patterns = ["abc"]
+    assert_equal "[FILTERED]", filter.append("ab")
+    assert_empty filter.finish # 新的疑似前缀紧邻已隐藏区域，不能重复输出替换标记。
+
+    filter = Expect::Redactor.new(%w[aaaa long-pattern])
+    assert_empty filter.append("aaaaa")
+    filter.patterns = []
+    assert_equal "[FILTERED]!", filter.append("!") + filter.finish
+  end
+
+  private
+
+  # 独立参考模型：逐偏移比较完整秘密，再合并布尔掩码；不复用生产代码的扫描/输出实现。
+  def reference_redact(input, patterns, partial:)
+    hidden = Array.new(input.bytesize, false)
+    patterns.each do |pattern|
+      input.bytesize.times do |offset|
+        next unless input.byteslice(offset, pattern.bytesize) == pattern
+
+        pattern.bytesize.times { |length| hidden[offset + length] = true }
+      end
+      next unless partial
+
+      (1...pattern.bytesize).each do |length|
+        next unless input.end_with?(pattern.byteslice(0, length))
+
+        ((input.bytesize - length)...input.bytesize).each { |offset| hidden[offset] = true }
+      end
+    end
+    output = +"".b
+    input.bytes.each_with_index do |byte, offset|
+      if hidden[offset]
+        output << "[FILTERED]" if offset.zero? || !hidden[offset - 1]
+      else
+        output << byte
+      end
+    end
+    output
+  end
+end

data/test/terminal_cleanup_test.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TerminalCleanupTest < ExpectTest
+  def test_read_failures_preserve_identity_reap_helper_and_leave_main_session_usable
+    [IOError.new("read failed"), Interrupt.new("interrupted"), SystemExit.new(17)].each do |failure|
+      session = terminal_session
+      main_pid = session.pid
+      with_stty_pipe do |reader, sink, spawned|
+        reader.stub(:read, -> { raise failure }) do
+          assert_same failure, assert_raises(failure.class) { bounded { session.stty } }
+        end
+        assert reader.closed?
+        assert sink.closed?
+        assert_reaped spawned.fetch(:pid)
+      end
+      assert_main_session_usable session, main_pid
+    end
+  end
+
+  def test_read_error_wins_over_close_error_and_helper_is_still_reaped
+    session = terminal_session
+    failure = IOError.new("read failed")
+    attempts = 0
+    with_stty_pipe do |reader, sink, spawned|
+      reader.stub(:read, -> { raise failure }) do
+        reader.stub(:close, lambda {
+          attempts += 1
+          raise IOError, "close failed"
+        }) do
+          assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+          refute reader.closed?, "permanently failing close must not be reported as closed"
+          assert sink.closed?
+          assert_reaped spawned.fetch(:pid)
+        end
+      end
+    end
+    assert_equal 1, attempts
+  end
+
+  def test_cleanup_error_after_success_is_visible_even_inside_caller_rescue
+    session = terminal_session
+    failure = IOError.new("close failed")
+    begin
+      raise ArgumentError, "already handled"
+    rescue ArgumentError
+      with_stty_pipe do |reader, sink, spawned|
+        reader.stub(:close, -> { raise failure }) do
+          assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+          assert sink.closed?
+          assert_reaped spawned.fetch(:pid)
+        end
+      end
+    end
+  end
+
+  def test_spawn_failure_attempts_both_closes_and_keeps_missing_command_cause
+    session = terminal_session
+    reader, sink = IO.pipe
+    @ios.push(reader, sink)
+    failure = Errno::ENOENT.new("missing stty")
+    IO.stub(:pipe, [reader, sink]) do
+      Process.stub(:spawn, ->(*) { raise failure }) do
+        Process.stub(:kill, ->(*) { flunk "no helper was spawned" }) do
+          reader.stub(:close, -> { raise IOError, "reader close failed" }) do
+            error = assert_raises(IOError) { session.stty }
+            assert_match "stty executable not found", error.message
+            assert_same failure, error.cause
+            assert sink.closed?
+          end
+        end
+      end
+    end
+  end
+
+  def test_externally_reaped_helper_is_not_signalled_and_does_not_change_main_status
+    session = terminal_session
+    main_pid = session.pid
+    failure = IOError.new("read failed after external wait")
+    with_stty_pipe do |reader, _sink, spawned|
+      reader.stub(:read, lambda {
+        bounded { Process.waitpid2(spawned.fetch(:pid)) }
+        raise failure
+      }) do
+        Process.stub(:kill, ->(*) { flunk "must not signal an externally reaped PID" }) do
+          assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+        end
+      end
+      assert_reaped spawned.fetch(:pid)
+    end
+    assert_main_session_usable session, main_pid
+  end
+
+  def test_uncooperative_helper_is_killed_and_reaped_after_read_failure
+    session = terminal_session
+    failure = IOError.new("read failed")
+    command = [RbConfig.ruby, "--disable-gems", "-e",
+               'Signal.trap("TERM", "IGNORE"); STDOUT.sync = true; puts "ready"; sleep 60']
+    signals = []
+    kill = Process.method(:kill)
+    with_stty_pipe(command: command) do |reader, _sink, spawned|
+      read = reader.method(:gets)
+      reader.stub(:read, lambda {
+        assert_equal("ready\n", bounded { read.call })
+        raise failure
+      }) do
+        Process.stub(:kill, lambda { |signal, pid|
+          signals << [signal, pid]
+          kill.call(signal, pid)
+        }) do
+          assert_same failure, assert_raises(IOError) { bounded(2) { session.stty } }
+        end
+      end
+      assert_equal [["TERM", spawned.fetch(:pid)], ["KILL", spawned.fetch(:pid)]], signals
+      assert_reaped spawned.fetch(:pid)
+    end
+  end
+
+  def test_normal_wait_retries_eintr_without_signalling_or_sleeping
+    session = terminal_session
+    wait = Process.method(:waitpid2)
+    attempts = 0
+    with_stty_pipe do |_reader, _sink, spawned|
+      Process.stub(:waitpid2, lambda { |pid, *flags|
+        assert_equal spawned.fetch(:pid), pid
+        attempts += 1
+        raise Errno::EINTR if attempts == 1
+
+        wait.call(pid, *flags)
+      }) do
+        session.stub(:sleep, ->(*) { flunk "successful stty must not add a fixed delay" }) do
+          Process.stub(:kill, ->(*) { flunk "successful helper must not be signalled" }) do
+            refute_empty session.stty
+          end
+        end
+      end
+      assert_equal 2, attempts
+      assert_reaped spawned.fetch(:pid)
+    end
+  end
+
+  def test_continuous_cleanup_eintr_has_a_fixed_budget_and_detaches_real_helper
+    session = terminal_session
+    failure = IOError.new("read failed")
+    clock = 0.0
+    waiter = nil
+    detach = Process.method(:detach)
+    attempts = 0
+    with_stty_pipe do |reader, _sink, spawned|
+      reader.stub(:read, -> { raise failure }) do
+        Expect.stub(:monotonic, -> { clock }) do
+          session.stub(:sleep, ->(duration) { clock += duration }) do
+            Process.stub(:waitpid2, lambda { |pid, flags|
+              assert_equal spawned.fetch(:pid), pid
+              assert_equal Process::WNOHANG, flags
+              attempts += 1
+              raise Errno::EINTR
+            }) do
+              Process.stub(:kill, ->(*) { flunk "ownership has not been checked successfully" }) do
+                Process.stub(:detach, lambda { |pid|
+                  assert_equal spawned.fetch(:pid), pid
+                  waiter = detach.call(pid)
+                }) do
+                  assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+                end
+              end
+            end
+          end
+        end
+      end
+      assert_operator attempts, :>, 3
+      assert_in_delta 0.15, clock, 0.000001
+      refute_nil waiter
+      assert_instance_of(Process::Status, bounded { waiter.value })
+      assert_reaped spawned.fetch(:pid)
+    end
+  end
+
+  def test_esrch_between_poll_and_signal_still_reaps_without_fabricating_status
+    session = terminal_session
+    main_pid = session.pid
+    failure = IOError.new("read failed")
+    clock = 0.0
+    signalled = false
+    wait = Process.method(:waitpid2)
+    with_stty_pipe do |reader, _sink, spawned|
+      reader.stub(:read, -> { raise failure }) do
+        Expect.stub(:monotonic, -> { clock }) do
+          session.stub(:sleep, ->(duration) { clock += duration }) do
+            Process.stub(:waitpid2, lambda { |pid, flags|
+              assert_equal Process::WNOHANG, flags
+              signalled ? wait.call(pid, flags) : nil
+            }) do
+              Process.stub(:kill, lambda { |signal, pid|
+                assert_equal "TERM", signal
+                assert_equal spawned.fetch(:pid), pid
+                bounded { wait.call(pid) }
+                signalled = true
+                raise Errno::ESRCH
+              }) do
+                Process.stub(:detach, ->(*) { flunk "ECHILD already released ownership" }) do
+                  assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+                end
+              end
+            end
+          end
+        end
+      end
+      assert signalled
+      assert_reaped spawned.fetch(:pid)
+    end
+    assert_main_session_usable session, main_pid
+  end
+
+  def test_sink_close_failure_still_attempts_reader_close_and_reaps_helper
+    session = terminal_session
+    failure = IOError.new("sink close failed")
+    attempts = 0
+    with_stty_pipe do |reader, sink, spawned|
+      sink.stub(:close, lambda {
+        attempts += 1
+        raise failure
+      }) do
+        assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+        assert reader.closed?
+        refute sink.closed?
+        assert_reaped spawned.fetch(:pid)
+      end
+    end
+    assert_equal 2, attempts
+  end
+
+  def test_forked_copy_closes_local_pipes_without_reaping_or_signalling_parent_helper
+    session = terminal_session
+    current_pid = Process.pid
+    failure = IOError.new("unwind in forked copy")
+    with_stty_pipe do |reader, sink, _spawned|
+      Process.stub(:pid, -> { current_pid }) do
+        reader.stub(:read, lambda {
+          current_pid = -1 # 在资源登记后模拟 fork 子进程的身份，父进程仍拥有辅助 PID。
+          raise failure
+        }) do
+          Process.stub(:waitpid2, ->(*) { flunk "non-owner must not wait for the parent's helper" }) do
+            Process.stub(:kill, ->(*) { flunk "non-owner must not signal the parent's helper" }) do
+              Process.stub(:detach, ->(*) { flunk "non-owner must not detach the parent's helper" }) do
+                assert_same failure, assert_raises(IOError) { session.stty }
+                assert reader.closed?
+                assert sink.closed?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def test_ledger_initialization_failure_still_closes_both_pipes
+    session = terminal_session
+    [IOError.new("ledger failed"), Interrupt.new("interrupted registration")].each do |failure|
+      with_stty_pipe do |reader, sink, spawned|
+        Expect::SessionResources.stub(:new, ->(*) { raise failure }) do
+          assert_same failure, assert_raises(failure.class) { session.stty }
+          assert reader.closed?
+          assert sink.closed?
+          assert_empty spawned
+        end
+      end
+    end
+  end
+
+  def test_fork_during_cleanup_wait_stops_process_cleanup
+    session = terminal_session
+    current_pid = Process.pid
+    failure = IOError.new("read failed")
+    with_stty_pipe do |reader, sink, _spawned|
+      Process.stub(:pid, -> { current_pid }) do
+        reader.stub(:read, -> { raise failure }) do
+          session.stub(:sleep, ->(*) { current_pid = -1 }) do
+            Process.stub(:waitpid2, ->(*) {}) do
+              Process.stub(:kill, ->(*) { flunk "fork during wait must release inherited process ownership" }) do
+                Process.stub(:detach, ->(*) { flunk "non-owner must not detach" }) do
+                  assert_same failure, assert_raises(IOError) { bounded { session.stty } }
+                  assert reader.closed?
+                  assert sink.closed?
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  def terminal_session
+    session = child(<<~'RUBY', raw_pty: true)
+      puts "ready"
+      while (line = STDIN.gets)
+        puts "reply:#{line.strip}"
+      end
+    RUBY
+    assert_equal 1, session.expect("ready", timeout: 2)
+    session
+  end
+
+  def assert_main_session_usable(session, main_pid)
+    assert_equal main_pid, session.pid
+    assert_nil session.process_status
+    refute session.closed?
+    session.puts "still usable"
+    assert_equal 1, session.expect("reply:still usable", timeout: 2)
+  end
+
+  def assert_reaped(pid)
+    assert_raises(Errno::ECHILD) { Process.waitpid(pid, Process::WNOHANG) }
+  end
+
+  # 只替换本次 stty 的管道；即使断言失败，恢复全局 stub 后仍由探针回收自己的真实子进程。
+  def with_stty_pipe(command: nil)
+    reader, sink = IO.pipe
+    @ios.push(reader, sink)
+    spawned = {}
+    spawn = Process.method(:spawn)
+    IO.stub(:pipe, [reader, sink]) do
+      Process.stub(:spawn, lambda { |*arguments, **options|
+        spawned[:pid] = spawn.call(*(command || arguments), **options)
+      }) do
+        yield reader, sink, spawned
+      end
+    end
+  ensure
+    reap_probe_child(spawned[:pid]) if spawned && spawned[:pid]
+  end
+
+  def reap_probe_child(pid)
+    return if Process.waitpid(pid, Process::WNOHANG)
+
+    begin
+      Process.kill("KILL", pid)
+    rescue Errno::ESRCH
+      nil
+    end
+    bounded { Process.waitpid(pid) }
+  rescue Errno::ECHILD
+    nil
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - expect-pty contributors
@@ -111,6 +111,7 @@ files:
 - README.md
 - Rakefile
 - benchmark/matching.rb
+- benchmark/redactor.rb
 - benchmark/relay.rb
 - benchmark/scaling.rb
 - benchmark/send_slow.rb
@@ -169,6 +170,7 @@ files:
 - test/multi_session_test.rb
 - test/pattern_offset_test.rb
 - test/process_test.rb
+- test/redactor_test.rb
 - test/relay_recovery_test.rb
 - test/release_test.rb
 - test/ruby_api_test.rb
@@ -177,6 +179,7 @@ files:
 - test/support/interact_probe.rb
 - test/support/kibitz_probe.rb
 - test/support/script_probe.rb
+- test/terminal_cleanup_test.rb
 - test/test_helper.rb
 - test/timeout_test.rb
 homepage: https://github.com/gatework/expect-ruby