expect-pty 0.5.1 → 0.5.3

data/lib/expect.rb

@@ -24,6 +24,7 @@ class Expect
   private_constant :CONFIGURATION_MUTEX
 
   class SpawnError < StandardError; end
+  class ReentrancyError < StandardError; end
 
   # 已被底层接受的字节不可撤回；调用方可据此只处理尚未写出的后缀。
   class WriteTimeout < IOError
@@ -70,7 +71,7 @@ class Expect
       raise
     ensure
       if session && (block_given? || !spawned)
-        session.__send__(:cleanup_preserving_failure, failed) do
+        session.__send__(:cleanup, failed: failed) do
           session.close(graceful: spawned && session.graceful_close?)
         end
       end
@@ -89,8 +90,9 @@ class Expect
       raise
     ensure
       if session && (block_given? || !initialized)
-        session.__send__(:cleanup_preserving_failure, failed) do
-          session.close(graceful: initialized && session.graceful_close?)
+        session.__send__(:cleanup, failed: failed) do
+          session.__send__(:cleanup_session, io, writer: writer, own: own,
+                                                 graceful: initialized && session.graceful_close?)
         end
       end
     end
@@ -189,7 +191,7 @@ class Expect
     failed = true
     raise
   ensure
-    cleanup_preserving_failure(failed) { close(graceful: false) } if @resources && !initialized
+    cleanup(failed:) { cleanup_session(master, writer: master, slave: slave, own: true) } unless initialized
   end
 
   # 在新控制终端中执行命令并同步确认 exec 结果；同一会话只能启动一次。
@@ -273,7 +275,12 @@ class Expect
   def pid = @resources.pid
 
   # 非阻塞回收并缓存子进程状态；未退出或仅适配 IO 时返回 nil。
-  def process_status = @resources.reap
+  def process_status
+    @resources.reap
+  rescue Errno::EINTR
+    # 单次轮询被中断时状态仍未知；wait/close 会在原期限内继续，不在这里无限重试。
+    @resources.status
+  end
 
   def exit_code = process_status&.exitstatus
 
@@ -332,7 +339,8 @@ class Expect
     offset = 0
     while offset < data.bytesize
       begin
-        count = writer.write_nonblock(data.byteslice(offset, READ_SIZE), exception: false)
+        chunk = data.byteslice(offset, READ_SIZE)
+        count = writer.write_nonblock(chunk, exception: false)
       rescue Errno::EINTR
         raise WriteTimeout.new(bytes_written: offset) if deadline && Expect.monotonic >= deadline
 
@@ -360,6 +368,10 @@ class Expect
           next
         end
       else
+        unless count.is_a?(Integer) && count.positive? && count <= chunk.bytesize
+          raise IOError, "write must return the number of accepted bytes"
+        end
+
         offset += count
       end
     end
@@ -400,15 +412,7 @@ class Expect
 
   # 轮询回收状态直到进程退出或期限到达；返回 Process::Status 或 nil，超时不丢弃 PID。
   def wait(timeout: nil)
-    period = Expect.duration(timeout)
-    deadline = period && (Expect.monotonic + period)
-    loop do
-      status = process_status
-      return status if status || !pid
-      return nil if deadline && Expect.monotonic >= deadline
-
-      sleep(deadline ? [0.01, deadline - Expect.monotonic].min.clamp(0, 0.01) : 0.01)
-    end
+    wait_for_child(Expect.duration(timeout))
   end
 
   # 先在自然退出期限内收集尾部输出，再关闭句柄并最多发送 TERM；不会发送 KILL。
@@ -425,8 +429,8 @@ class Expect
 
       read_available
     end
-    finish_close(timeout: deadline ? [deadline - Expect.monotonic, 0].max : nil,
-                 term_timeout: term_timeout, force: false)
+    close_resources(timeout: deadline ? [deadline - Expect.monotonic, 0].max : nil,
+                    term_timeout: term_timeout, force: false)
   end
 
   # 立即关闭句柄，再分阶段等待、TERM、KILL；不收集剩余输出，返回已回收状态或 nil。
@@ -434,7 +438,7 @@ class Expect
     period = Expect.duration(timeout)
     raise ArgumentError, "hard_close timeout must be finite" unless period
 
-    finish_close(timeout: period, term_timeout: period, force: true)
+    close_resources(timeout: period, term_timeout: period, force: true)
   end
 
   # 通用生命周期清理：可先软关闭，ensure 中硬关闭兜底；正常完成返回 nil。
@@ -445,20 +449,29 @@ class Expect
     failed = true
     raise
   ensure
-    cleanup_preserving_failure(failed) { hard_close }
+    cleanup(failed:) { hard_close }
   end
 
   private
 
+  # 账本发布前只按局部所有权清理；发布后沿用完整关闭流程，避免两套生命周期状态。
+  def cleanup_session(reader, writer:, own:, slave: nil, graceful: false)
+    if @resources
+      close(graceful: graceful)
+    elsif own
+      SessionResources.close_handles(reader, writer, slave)
+    end
+  end
+
   # 仅在本次生命周期已有异常时抑制常规清理错误；调用者 rescue 中的旧异常不算本次失败。
-  def cleanup_preserving_failure(failed)
+  def cleanup(failed:)
     yield
   rescue IOError, SystemCallError
     raise unless failed
   end
 
   # 共用的进程关闭流程；force 控制是否允许 KILL，只有资源创建者能够操作直属子进程。
-  def finish_close(timeout:, term_timeout:, force:)
+  def close_resources(timeout:, term_timeout:, force:)
     failure = nil
     # 预期的清理错误延后传播，保证其余所属资源和直属子进程仍能完成清理。
     cleanup = lambda do |&step|
@@ -480,7 +493,7 @@ class Expect
     @relay_outputs&.clear
     @relay_history&.clear
     @relay_callback = nil
-    status = finish_child_close(timeout: timeout, term_timeout: term_timeout, force: force)
+    status = close_child(timeout: timeout, term_timeout: term_timeout, force: force)
     completed = true
     status
   ensure
@@ -494,17 +507,41 @@ class Expect
   end
 
   # 句柄清理失败不改变进程策略；未回收 PID 保留给重复关闭或终结器继续处理。
-  def finish_child_close(timeout:, term_timeout:, force:)
+  def close_child(timeout:, term_timeout:, force:)
     return process_status unless @resources.owner == Process.pid && pid
-    return process_status if wait(timeout: timeout)
 
-    signal_child("TERM")
-    return process_status if wait(timeout: term_timeout)
+    status = wait(timeout: timeout)
+    return status if status || !pid
 
+    status = wait_for_child(term_timeout, signal: "TERM")
+    return status if status || !pid
     return unless force
 
-    signal_child("KILL")
-    wait(timeout: 1)
+    wait_for_child(1, signal: "KILL")
+  end
+
+  # 每阶段只计算一次期限；回收或信号被中断后仍沿用剩余预算，零预算也先做一次尝试。
+  def wait_for_child(period, signal: nil)
+    deadline = period && (Expect.monotonic + period)
+    loop do
+      status = process_status
+      return status if status || !pid || @resources.owner != Process.pid
+
+      begin
+        signal_child(signal) if signal
+        signal = nil
+      rescue Errno::EINTR
+        # 下轮先回收再重试信号，避免在无限等待或持续中断时忙等。
+        nil
+      end
+      # ESRCH 后可能已完成回收；即使预算耗尽，也要返回刚获得的状态。
+      return process_status unless pid
+
+      remaining = deadline && (deadline - Expect.monotonic)
+      return nil if remaining && remaining <= 0
+
+      sleep(remaining ? [0.01, remaining].min : 0.01)
+    end
   end
 
   # 统一初始化 PTY 与已有 IO 会话，复制配置并注册不直接捕获会话的资源终结器。
@@ -580,13 +617,13 @@ class Expect
       # 某些系统用 PTY 的 EIO 表示对端关闭；普通 IO 的同类错误仍按异常处理。
       raise unless @pty
 
-      return finish_read
+      return mark_eof
     rescue EOFError
-      return finish_read
+      return mark_eof
     end
     return nil if data == :wait_readable
 
-    return finish_read if data.nil?
+    return mark_eof if data.nil?
 
     data = data.b
     buffer << data
@@ -599,7 +636,7 @@ class Expect
     data
   end
 
-  def finish_read
+  def mark_eof
     @eof = true
     flush_log
     flush_diagnostics(:received)
@@ -619,7 +656,7 @@ class Expect
 
   # 仅由资源创建者向仍未回收的子进程发送信号；若进程刚好退出，则尝试回收。
   def signal_child(signal)
-    return unless alive? && @resources.owner == Process.pid
+    return unless pid && @resources.owner == Process.pid
 
     Process.kill(signal, pid)
   rescue Errno::ESRCH

data/script/release.rb

@@ -26,7 +26,7 @@ class Release
   end
 
   def run
-    notes = self.class.release_notes(File.read("CHANGELOG.md"), @version)
+    notes = self.class.read_notes("CHANGELOG.md", @version)
     unless @dry_run || capture("git", "status", "--porcelain").empty?
       raise "Commit all source changes before publishing"
     end
@@ -46,7 +46,7 @@ class Release
     @checksum_file = File.join(directory, "SHA256SUMS")
     @notes_file = File.join(directory, "release-notes.md")
     File.write(@checksum_file, "#{@sha256}  #{File.basename(@artifact)}\n")
-    File.write(@notes_file, "#{notes}\n")
+    File.write(@notes_file, "#{notes}\n", encoding: "UTF-8")
     puts "Verified #{@tag}: #{@sha256}\nArtifact: #{@artifact}"
     return puts "Dry run complete: #{@artifact}" if @dry_run
 
@@ -61,6 +61,14 @@ class Release
   end
 
   # 有未归档的变更时拒绝发布，避免把新接口放进旧版本或遗漏发布说明。
+  def self.read_notes(path, version)
+    changelog = File.read(path, encoding: "UTF-8")
+    raise "Invalid UTF-8 in #{path}" unless changelog.valid_encoding?
+
+    release_notes(changelog, version)
+  end
+
+  # 纯章节解析与文件编码边界分离，本地入口和工作流共用 read_notes。
   def self.release_notes(changelog, version)
     raise "Use a stable X.Y.Z version" unless /\A\d+\.\d+\.\d+\z/.match?(version)
 

data/test/initialization_failure_test.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "minitest/mock"
+
+class InitializationFailureTest < ExpectTest
+  def test_new_closes_both_pty_ends_before_propagating_the_original_exception
+    initialization_errors.each do |failure|
+      master, slave = PTY.open
+      @ios.push(master, slave)
+      PTY.stub(:open, [master, slave]) do
+        without_ledger(failure) do
+          assert_same failure, assert_raises(failure.class) { Expect.new }
+          assert master.closed?, "master leaked before test cleanup"
+          assert slave.closed?, "slave leaked before test cleanup"
+        end
+      end
+    end
+  end
+
+  def test_open_cleans_owned_handles_and_preserves_borrowed_handles
+    [true, false].product(initialization_errors).each do |own, failure|
+      reader, writer = IO.pipe
+      @ios.push(reader, writer)
+      without_ledger(failure) do
+        assert_same failure, assert_raises(failure.class) { Expect.open(reader, writer: writer, own: own) }
+        assert_equal own, reader.closed?
+        assert_equal own, writer.closed?
+      end
+    end
+  end
+
+  def test_duplicate_owned_handle_is_attempted_once_even_when_close_fails
+    reader, writer = IO.pipe
+    @ios.push(reader, writer)
+    calls = 0
+    reader.stub(:close, lambda {
+      calls += 1
+      raise IOError, "injected close failure"
+    }) do
+      without_ledger(failure = Interrupt.new) do
+        assert_same failure, assert_raises(Interrupt) { Expect.open(reader, own: true) }
+        assert_equal 1, calls
+      end
+    end
+  end
+
+  def test_cleanup_failure_still_attempts_other_handles_and_keeps_primary_exception
+    initialization_errors.each do |failure|
+      reader, writer = IO.pipe
+      @ios.push(reader, writer)
+      reader.stub(:close, -> { raise Errno::EIO }) do
+        without_ledger(failure) do
+          assert_same failure, assert_raises(failure.class) { Expect.open(reader, writer: writer, own: true) }
+          assert writer.closed?
+        end
+      end
+    end
+  end
+
+  def test_new_cleanup_failure_still_closes_slave
+    master, slave = PTY.open
+    @ios.push(master, slave)
+    PTY.stub(:open, [master, slave]) do
+      master.stub(:close, -> { raise IOError, "injected close failure" }) do
+        without_ledger(failure = SystemExit.new(17)) do
+          assert_same failure, assert_raises(SystemExit) { Expect.new }
+          assert slave.closed?
+        end
+      end
+    end
+  end
+
+  def test_invalid_non_io_argument_is_not_closed_by_the_fallback
+    reader, writer = IO.pipe
+    @ios.push(reader, writer)
+    invalid = Object.new
+    invalid.define_singleton_method(:close) { raise "must not close non-IO objects" }
+    without_ledger(failure = Interrupt.new) do
+      assert_same failure, assert_raises(Interrupt) { Expect.open(invalid, writer: writer, own: true) }
+      assert writer.closed?
+    end
+  end
+
+  private
+
+  def initialization_errors = [Interrupt.new("injected initialization interruption"), SystemExit.new(17)]
+
+  def without_ledger(failure, &)
+    Expect::SessionResources.stub(:new, ->(*, **) { raise failure }, &)
+  end
+end

data/test/integration/README.md

@@ -8,9 +8,11 @@ SSH_HOST=127.0.0.1 SSH_USER=crate ruby test/integration/ssh_scripts.rb
 SSH_HOST=127.0.0.1 SSH_USER=crate bundle exec rake test:ssh
 ```
 
-脚本隐藏读取密码；也支持由运行环境提供 `EXPECT_PASSWORD`。密码不会作为 SSH 命令行参数传递，日志在认证完成后才开启。默认自动测试不连接 SSH、不读取密码。
+脚本隐藏读取密码；也支持由运行环境提供 `EXPECT_PASSWORD`。密码不会作为 SSH 命令行参数传递，日志在认证完成后才开启。默认自动测试不连接
+SSH、不读取密码。
 
-支持 `SSH_PORT`（默认 22）、`EXPECT_LOG_DIR`（日志根目录）、`SSH_KNOWN_HOSTS`。连接非本机主机时，必须提供已有的受信任 known_hosts，例如：
+支持 `SSH_PORT`（默认 22）、`EXPECT_LOG_DIR`（日志根目录）、`SSH_KNOWN_HOSTS`。连接非本机主机时，必须提供已有的受信任
+known_hosts，例如：
 
 ```sh
 SSH_HOST=192.0.2.10 SSH_USER=operator SSH_PORT=22 \
@@ -18,23 +20,27 @@ SSH_HOST=192.0.2.10 SSH_USER=operator SSH_PORT=22 \
   EXPECT_LOG_DIR=tmp/device-check ruby test/integration/ssh_scripts.rb
 ```
 
-这是 POSIX shell 脚本测试；厂商专用 CLI（如交换机的 `show` 命令、分页提示符）需要对应设备的命令和预期输出，不能直接使用这些 shell fixtures。
+这是 POSIX shell 脚本测试；厂商专用 CLI（如交换机的 `show` 命令、分页提示符）需要对应设备的命令和预期输出，不能直接使用这些
+shell fixtures。
 
 ## 同一个登录会话执行的脚本
 
-| 脚本 | 验证内容 | 预期退出码 |
-| --- | --- | --- |
-| `01_identity.sh` | 当前用户、远端 PTY、完成标记 | 0 |
-| `02_output.sh` | stdout、stderr、中文和输出顺序 | 0 |
-| `03_delayed.sh` | 分三次延迟输出，确保日志完整 | 0 |
-| `04_failure.sh` | 明确输出错误并退出 | 7（预期失败） |
-| `05_recovery.sh` | 上个脚本失败后继续执行，计算结果为 42 | 0 |
+| 脚本             | 验证内容                              | 预期退出码    |
+|------------------|---------------------------------------|---------------|
+| `01_identity.sh` | 当前用户、远端 PTY、完成标记          | 0             |
+| `02_output.sh`   | stdout、stderr、中文和输出顺序        | 0             |
+| `03_delayed.sh`  | 分三次延迟输出，确保日志完整          | 0             |
+| `04_failure.sh`  | 明确输出错误并退出                    | 7（预期失败） |
+| `05_recovery.sh` | 上个脚本失败后继续执行，计算结果为 42 | 0             |
 
-fixtures 位于 `test/fixtures/ssh_scripts/`，都不修改目标文件或设备配置。文件内容通过 SSH 的交互 shell 传给独立 `/bin/sh -c` 执行，不需要上传文件。每个脚本都有随机开始/结束标记，结束标记携带真实 `$?`；脚本输出和退出码都必须符合预期才算通过。
+fixtures 位于 `test/fixtures/ssh_scripts/`，都不修改目标文件或设备配置。文件内容通过 SSH 的交互 shell 传给独立
+`/bin/sh -c` 执行，不需要上传文件。每个脚本都有随机开始/结束标记，结束标记携带真实 `$?`；脚本输出和退出码都必须符合预期才算通过。
 
-测试关闭终端回显和 shell 行编辑，使用单引号传输完整脚本，保留中文 UTF-8 和引号，避免 C locale 的交互式 readline 把高位字节当快捷键执行。末尾仍等待 shell 提示符，确认可以继续执行下一项。
+测试关闭终端回显和 shell 行编辑，使用单引号传输完整脚本，保留中文 UTF-8 和引号，避免 C locale 的交互式 readline
+把高位字节当快捷键执行。末尾仍等待 shell 提示符，确认可以继续执行下一项。
 
-另外执行两条日志控制命令：关闭日志后输出 `UNLOGGED_OUTPUT`，再以默认追加模式开启日志并输出 `APPEND_OK`。最后发送延迟输出及退出命令，只调用 `soft_close`，确认 `SESSION_FINAL_TAIL` 确实在关闭过程中写入日志。
+另外执行两条日志控制命令：关闭日志后输出 `UNLOGGED_OUTPUT`，再以默认追加模式开启日志并输出 `APPEND_OK`。最后发送延迟输出及退出命令，只调用
+`soft_close`，确认 `SESSION_FINAL_TAIL` 确实在关闭过程中写入日志。
 
 ## 检查和输出文件
 
@@ -43,11 +49,14 @@ fixtures 位于 `test/fixtures/ssh_scripts/`，都不修改目标文件或设备
 - `session.log`：收到的原始数据，以及手工添加的 `[SEND] 脚本名 sha256=...` 和 `[EXIT] 脚本名 status=...`。
 - `report.json`：主机、用户、远端 TTY、每项脚本输出和退出码、校验结果、SSH 退出码、日志字节数及 SHA-256。
 
-只有认证后的输出进入日志。Expect 自动记录接收字节，发送的脚本名称和摘要由 `write_log` 明确写入，便于审核执行了哪个 fixture；fixture 文件中的原文可以用报告内的 SHA-256 核对。
+只有认证后的输出进入日志。Expect 自动记录接收字节，发送的脚本名称和摘要由 `write_log` 明确写入，便于审核执行了哪个
+fixture；fixture 文件中的原文可以用报告内的 SHA-256 核对。
 
-共 11 项日志/流程检查：完整输出、执行顺序、即时 flush、stdout/stderr、UTF-8、非零退出后恢复、覆盖模式、暂停记录、追加模式、关闭前尾部输出、密码不出现在日志中。另校验日志条目没有重复，日志句柄在停止记录和关闭会话后正确关闭。
+共 11 项日志/流程检查：完整输出、执行顺序、即时
+flush、stdout/stderr、UTF-8、非零退出后恢复、覆盖模式、暂停记录、追加模式、关闭前尾部输出、密码不出现在日志中。另校验日志条目没有重复，日志句柄在停止记录和关闭会话后正确关闭。
 
-成功返回进程退出码 0。认证失败、超时、脚本输出错误、意外退出码或日志校验失败均返回非零，并在有报告目录时留下 `passed: false` 的报告。不用仅看到终端输出就判断成功；请查看最终 PASS 和 `report.json` 的 `passed`。
+成功返回进程退出码 0。认证失败、超时、脚本输出错误、意外退出码或日志校验失败均返回非零，并在有报告目录时留下 `passed: false`
+的报告。不用仅看到终端输出就判断成功；请查看最终 PASS 和 `report.json` 的 `passed`。
 
 ## 无需 SSH 的回归测试
 
@@ -56,7 +65,8 @@ bundle exec ruby -Itest test/script_logging_test.rb
 bundle exec rake test
 ```
 
-`test/script_logging_test.rb` 使用真实本地 PTY 执行相同 fixtures，另外验证回调日志、借用 File 日志、错误退出/错误输出的反例、引号和 shell 元字符、日志错误上抛，以及超时后继续收集日志。它和 SSH 脚本共享测试 helper，不依赖远端账户。
+`test/script_logging_test.rb` 使用真实本地 PTY 执行相同 fixtures，另外验证回调日志、借用 File 日志、错误退出/错误输出的反例、引号和
+shell 元字符、日志错误上抛，以及超时后继续收集日志。它和 SSH 脚本共享测试 helper，不依赖远端账户。
 
 ## SSH interact 人工和自动验证
 
@@ -67,13 +77,18 @@ ruby examples/ssh_interact.rb --auto
 bundle exec rake test:ssh_interact
 ```
 
-使用上述同一套 SSH 环境变量和隐藏密码输入。人工模式显示 `EXPECT_SCRIPT_PROMPT>`；输入命令有回显，Ctrl-C 传给远端前台任务。在命令结束、回到 shell 提示符后按 Ctrl-]，会关闭远端回显，执行 `MANUAL_AUTOMATION_RESUMED` 检查，再正常退出 SSH。也支持直接输入 `exit`：成功退出记为 `completion: remote_exit`，此路径不执行返回 expect 的检查。非零 SSH 退出仍判为失败。
+使用上述同一套 SSH 环境变量和隐藏密码输入。人工模式显示 `EXPECT_SCRIPT_PROMPT>`；输入命令有回显，Ctrl-C 传给远端前台任务。在命令结束、回到
+shell 提示符后按 Ctrl-]，会关闭远端回显，执行 `MANUAL_AUTOMATION_RESUMED` 检查，再正常退出 SSH。也支持直接输入 `exit`：成功退出记为
+`completion: remote_exit`，此路径不执行返回 expect 的检查。非零 SSH 退出仍判为失败。
 
-`--auto` 创建真实本地 PTY，验证两次 `interact` 接管、当前用户和远端 TTY、stdout/stderr/中文、Ctrl-C、Ctrl-]、转义后的本地尾部不进入 SSH、恢复 `expect` 及终端与监听设置。4 项命令输出和 13 项交互/日志检查全部通过后才返回 0。
+`--auto` 创建真实本地 PTY，验证两次 `interact` 接管、当前用户和远端 TTY、stdout/stderr/中文、Ctrl-C、Ctrl-]、转义后的本地尾部不进入
+SSH、恢复 `expect` 及终端与监听设置。4 项命令输出和 13 项交互/日志检查全部通过后才返回 0。
 
-日志在认证之后开启；每次在 `tmp/ssh-interact/` 新建 0700 目录，保存 0600 的 `session.log` 和 `report.json`。报告包含检查项、命令输出、SSH 退出码及日志摘要。自动模式也校验日志无重复、退出尾部不丢失、密码不出现在日志中。
+日志在认证之后开启；每次在 `tmp/ssh-interact/` 新建 0700 目录，保存 0600 的 `session.log` 和 `report.json`
+。报告包含检查项、命令输出、SSH 退出码及日志摘要。自动模式也校验日志无重复、退出尾部不丢失、密码不出现在日志中。
 
-无需 SSH 的回归位于 `test/interact_test.rb`，覆盖可见输入、Ctrl-C、两次接管、返回自动命令、超时、两端 EOF、回调异常和输出 IO 故障时的终端恢复。`test/script_logging_test.rb` 另验证 CRLF 输出边界，包括空输出、末尾有/无换行和多个换行。
+无需 SSH 的回归位于 `test/interact_test.rb`，覆盖可见输入、Ctrl-C、两次接管、返回自动命令、超时、两端 EOF、回调异常和输出 IO
+故障时的终端恢复。`test/script_logging_test.rb` 另验证 CRLF 输出边界，包括空输出、末尾有/无换行和多个换行。
 
 ## `ssh_auto.rb` 环境检查
 
@@ -85,6 +100,10 @@ ruby examples/ssh_auto.rb --no-interact
 bundle exec rake test:ssh_auto
 ```
 
-该示例自动登录 `SSH_HOST`（默认 `127.0.0.1`），用本库的 `write` / `expect` 顺序执行文件顶部的 `COMMANDS`，显示真实输出并检查退出码。默认命令为 `id`、`uname -srm`、`sw_vers`、`df -h /` 和 `uptime`，不修改系统设置；可直接修改数组来下发其他 macOS/POSIX shell 命令。它不依赖 `test/support`，`ScriptProbe.check` 只供测试脚本使用。
+该示例自动登录 `SSH_HOST`（默认 `127.0.0.1`），用本库的 `write` / `expect` 顺序执行文件顶部的 `COMMANDS`，显示真实输出并检查退出码。默认命令为
+`id`、`uname -srm`、`sw_vers`、`df -h /` 和 `uptime`，不修改系统设置；可直接修改数组来下发其他 macOS/POSIX shell 命令。它不依赖
+`test/support`，`ScriptProbe.check` 只供测试脚本使用。
 
-执行成功后默认进入 `interact`，输入有回显，Ctrl-C 发给远端前台任务；`exit` 或 Ctrl-] 结束连接。使用 `--no-interact` 则执行完退出。`EXPECT_LOG_DIR` 可指定日志目录，默认 `tmp/ssh-auto/`；每次创建独立 0600 日志，记录命令和远端输出，认证前关闭日志。此使用示例不生成 JSON 测试报告，详细日志断言仍由 `ssh_scripts.rb` 和 `ssh_interact.rb --auto` 验证。
+执行成功后默认进入 `interact`，输入有回显，Ctrl-C 发给远端前台任务；`exit` 或 Ctrl-] 结束连接。使用 `--no-interact` 则执行完退出。
+`EXPECT_LOG_DIR` 可指定日志目录，默认 `tmp/ssh-auto/`；每次创建独立 0600 日志，记录命令和远端输出，认证前关闭日志。此使用示例不生成
+JSON 测试报告，详细日志断言仍由 `ssh_scripts.rb` 和 `ssh_interact.rb --auto` 验证。