expect-pty 0.2.0

data/examples/ssh_interact.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Run from the checkout or the unpacked gem. Test helpers use only standard
+# libraries; Minitest is not needed for this live SSH example.
+require "io/console"
+require "json"
+require "fileutils"
+require "tmpdir"
+require "time"
+require_relative "../test/support/interact_probe"
+
+if ARGV.delete("--help")
+  puts <<~HELP
+    Usage: ruby examples/ssh_interact.rb [--auto]
+
+    Default: SSH login with visible typing; Ctrl-] returns to expect, exit ends SSH.
+    --auto:  Drive a real local PTY to verify commands, Ctrl-C, Ctrl-] and reentry.
+
+    Environment: SSH_HOST (127.0.0.1), SSH_USER (current user), SSH_PORT (22),
+                 SSH_KNOWN_HOSTS, EXPECT_PASSWORD, EXPECT_LOG_DIR.
+    Password input is hidden. Non-loopback hosts require SSH_KNOWN_HOSTS.
+    Logs and JSON reports default to tmp/ssh-interact/ in this project.
+  HELP
+  exit
+end
+automatic = !ARGV.delete("--auto").nil?
+abort "unknown arguments: #{ARGV.join(" ")} (use --help)" unless ARGV.empty?
+abort "manual interact requires a terminal; use --auto for unattended testing" unless automatic || $stdin.tty?
+
+host = ENV.fetch("SSH_HOST", "127.0.0.1")
+user = ENV.fetch("SSH_USER", ENV.fetch("USER", "crate"))
+port = Integer(ENV.fetch("SSH_PORT", "22"), 10)
+ScriptProbe.check((1..65_535).cover?(port), "SSH_PORT must be between 1 and 65535")
+ScriptProbe.check([host, user].none? do |value|
+  value.empty? || value.start_with?("-") || value.match?(/[\s\x00]/)
+end, "invalid SSH host or user")
+known_hosts = ENV.fetch("SSH_KNOWN_HOSTS", nil)
+ScriptProbe.check(known_hosts || %w[127.0.0.1 ::1 localhost].include?(host),
+                  "SSH_KNOWN_HOSTS is required for remote hosts")
+
+password = ENV.delete("EXPECT_PASSWORD")&.dup
+unless password
+  $stderr.print("SSH password: ")
+  password = ($stdin.tty? ? $stdin.noecho(&:gets) : $stdin.gets)&.chomp
+  $stderr.puts
+end
+ScriptProbe.check(password && !password.empty? && !password.match?(/[\r\n\x00]/), "a single-line password is required")
+base = File.expand_path(ENV.fetch("EXPECT_LOG_DIR", File.expand_path("../tmp/ssh-interact", __dir__)))
+FileUtils.mkdir_p(base)
+directory = Dir.mktmpdir("#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}-", base)
+log_path = File.join(directory, "session.log")
+report_path = File.join(directory, "report.json")
+report = { mode: automatic ? "automatic" : "manual", host: host, port: port, user: user,
+           started_at: Time.now.utc.iso8601, passed: false, cases: [], checks: [] }
+session = nil
+local_terminal = nil
+
+begin
+  Dir.mktmpdir("expect-known-hosts-") do |temporary|
+    policy = known_hosts ? "yes" : "accept-new"
+    hosts_path = known_hosts || File.join(temporary, "known_hosts")
+    args = ["ssh", "-F", "/dev/null", "-tt", "-p", port.to_s,
+            "-o", "ConnectTimeout=5", "-o", "NumberOfPasswordPrompts=1",
+            "-o", "PreferredAuthentications=password", "-o", "PubkeyAuthentication=no",
+            "-o", "StrictHostKeyChecking=#{policy}", "-o", "UserKnownHostsFile=#{hosts_path}",
+            "-l", user, host, "env ENV= PS1=#{Shellwords.escape(ScriptProbe::PROMPT)} /bin/sh -i"]
+    session = Expect.spawn(*args, raw_pty: true, log_stdout: false, log_listeners: false,
+                                  debug_level: 0, write_timeout: 5)
+    login = session.expect(/password:\s*\z/i, /Permission denied/i, timeout: 10)
+    ScriptProbe.check(login == 1, "SSH password prompt missing (#{session.error || "authentication rejected"})")
+    session.write(password, "\n")
+    runner = ScriptProbe::Runner.new(session, timeout: 10).ready!
+    InteractProbe.prepare(session, echo: !automatic)
+    File.open(log_path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.truncate(0) }
+    session.log_to(log_path)
+
+    remote_exit = false
+    if automatic
+      report.merge!(InteractProbe.verify(session, user: user))
+    else
+      local_terminal = Expect.open($stdin)
+      initial_mode = InteractProbe.configuration(local_terminal)
+      puts "Logged in as #{user}@#{host}. Enter commands; press Ctrl-] to return to expect."
+      puts "Log: #{log_path}"
+      # prepare consumed the initial prompt while configuring remote echo.
+      $stdout.print(ScriptProbe::PROMPT)
+      $stdout.flush
+      # This is the actual public API handoff: stdin -> SSH, SSH -> stdout.
+      returned = session.interact(input: $stdin, escape: InteractProbe::ESCAPE, output: $stdout)
+      ScriptProbe.check(InteractProbe.configuration(local_terminal) == initial_mode,
+                        "stdin terminal mode was not restored")
+      report[:local_terminal_restored] = true
+      report[:checks] += %w[real_stdin_stdout terminal_restored]
+      if returned.equal?(session)
+        remote_exit = true
+        report[:completion] = "remote_exit"
+        session.soft_close(timeout: 3)
+        ScriptProbe.check(session.closed? && session.exit_code&.zero?,
+                          "SSH exited with status #{session.exit_code.inspect}")
+        report[:checks] << "remote_eof"
+      else
+        ScriptProbe.check(returned.is_a?(Expect) && returned.to_io.equal?($stdin), "unexpected interact termination")
+        ScriptProbe.check(session.alive?, "remote session ended during interaction")
+        report[:completion] = "local_escape"
+        report[:checks] += %w[ctrl_bracket_escape remote_alive]
+        puts "\nReturned from interact; verifying automated expect resumes..."
+        InteractProbe.prepare(session)
+        runner.run(
+          "expect_after_manual", "printf 'MANUAL_AUTOMATION_RESUMED\\n'",
+          expected_status: 0, expected_output: "MANUAL_AUTOMATION_RESUMED\n"
+        )
+        report[:cases] = runner.results
+        report[:checks] << "expect_resume"
+      end
+    end
+
+    runner.finish! unless remote_exit
+    report[:ssh_exit_code] = session.exit_code
+    text = ScriptProbe.normalize(File.binread(log_path))
+    report[:cases].each do |result|
+      output = result.fetch(:output).b
+      ScriptProbe.check(text.scan(Regexp.new(Regexp.escape(output), Regexp::NOENCODING)).length == 1,
+                        "#{result[:name]}: log output missing or duplicated")
+    end
+    unless remote_exit
+      ScriptProbe.check(text.scan("SESSION_FINAL_TAIL\n").length == 1,
+                        "shutdown tail missing or duplicated")
+    end
+    ScriptProbe.check(!text.include?(InteractProbe::TAIL), "local escape tail leaked to SSH") if automatic
+    ScriptProbe.check(!text.include?(password.b), "password detected in log")
+    report[:checks] += %w[unique_log_output eof_drain password_absent clean_ssh_exit]
+    report[:passed] = true
+  end
+rescue StandardError => error
+  report[:error] = "#{error.class}: #{error.message}".gsub(password, "[REDACTED]")
+ensure
+  session&.close
+  local_terminal&.close
+  if File.file?(log_path)
+    bytes = File.binread(log_path)
+    if bytes.include?(password.b)
+      File.binwrite(log_path, bytes.gsub(password.b, "[REDACTED]"))
+      report[:passed] = false
+      report[:error] = "password detected and removed from log"
+    end
+    report[:log_bytes] = File.size(log_path)
+    report[:log_sha256] = Digest::SHA256.file(log_path).hexdigest
+  end
+  password.replace("\0" * password.bytesize)
+  report[:finished_at] = Time.now.utc.iso8601
+  report[:log_path] = log_path
+  File.open(report_path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write(JSON.pretty_generate(report)) }
+end
+
+puts "Log: #{log_path}"
+puts "Report: #{report_path}"
+abort(report[:error]) unless report[:passed]
+puts "PASS #{report[:mode]} interact: #{report[:cases].length} command checks, " \
+     "#{report[:checks].length} interaction/log checks; SSH exit=0"

data/examples/ssh_login.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Optional real SSH integration check. Password input is hidden and never logged.
+require "io/console"
+require "tmpdir"
+require "securerandom"
+require_relative "../lib/expect/pty"
+
+host = ENV.fetch("SSH_HOST", "127.0.0.1")
+user = ENV.fetch("SSH_USER", ENV.fetch("USER", "crate"))
+abort "invalid SSH host or user" if [host, user].any? do |value|
+  value.empty? || value.start_with?("-") || value.match?(/[\s\x00]/)
+end
+password = ENV.delete("EXPECT_PASSWORD")&.dup
+unless password
+  $stderr.print("SSH password: ")
+  password = $stdin.tty? ? $stdin.noecho(&:gets) : $stdin.gets
+  $stderr.puts
+  password = password&.chomp
+end
+abort "password is required" if password.nil? || password.empty?
+
+begin
+  Dir.mktmpdir("expect-ssh-") do |dir|
+    # Isolated known_hosts keeps this example independent of user SSH settings.
+    # For non-loopback hosts, use an existing trusted known_hosts file.
+    known_hosts = ENV.fetch("SSH_KNOWN_HOSTS", nil)
+    abort "SSH_KNOWN_HOSTS is required for remote hosts" unless known_hosts || %w[127.0.0.1 ::1
+                                                                                  localhost].include?(host)
+    policy = known_hosts ? "yes" : "accept-new"
+    known_hosts ||= File.join(dir, "known_hosts")
+    arguments = ["ssh", "-F", "/dev/null", "-tt", "-o", "ConnectTimeout=5",
+                 "-o", "PreferredAuthentications=password", "-o", "PubkeyAuthentication=no",
+                 "-o", "NumberOfPasswordPrompts=1", "-o", "StrictHostKeyChecking=#{policy}",
+                 "-o", "UserKnownHostsFile=#{known_hosts}", "-l", user, host,
+                 "env PS1='EXPECT_SHELL> ' /bin/sh -i"]
+    Expect.spawn(*arguments, log_stdout: false, raw_pty: true) do |session|
+      prompt = session.expect(/password:\s*\z/i, /Permission denied/i, timeout: 10)
+      abort "SSH password prompt not received (#{session.error || "authentication rejected"})" unless prompt == 1
+      session.write(password, "\n")
+      password.replace("\0" * password.bytesize)
+
+      # Start a command after authentication. The marker is assembled remotely
+      # from two quoted arguments, so terminal command echo cannot satisfy it.
+      login = session.expect("EXPECT_SHELL> ", /Permission denied/i, timeout: 10)
+      abort "SSH login failed (#{session.error || "authentication rejected"})" unless login == 1
+      token = SecureRandom.hex(12)
+      session.write("printf '\\n%s%s\\n' 'EXPECT_OK_' '#{token}'; id -un; tty\n")
+      marker = session.expect(/EXPECT_OK_#{Regexp.escape(token)}\r?\n/, timeout: 10)
+      abort "remote command did not run (#{session.error})" unless marker
+      identity = session.expect(%r{([^\r\n]+)\r?\n(/dev/[^\r\n]+)\r?\n}, timeout: 5)
+      abort "remote identity/TTY response missing" unless identity
+      abort "unexpected SSH user" unless session.captures.first == user.b
+      puts "SSH password login verified: #{user}@#{host}"
+      puts "Remote identity: #{session.captures.first}; TTY: #{session.captures.last}"
+      session.write("exit\n")
+      session.soft_close(timeout: 5)
+      abort "SSH exit status #{session.exit_code.inspect}" unless session.exit_code&.zero?
+      puts "SSH exited cleanly (0)"
+    end
+  end
+ensure
+  password&.replace("\0" * password.bytesize)
+end

data/expect-pty.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/expect/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "expect-pty"
+  spec.version = Expect::VERSION
+  spec.authors = ["expect-pty contributors"]
+  spec.homepage = "https://github.com/gatework/expect-ruby"
+  spec.summary = "Ruby PTY automation with the Expect.pm interaction model"
+  spec.description = "Automate interactive programs with exact and regexp matching, " \
+                     "Ruby blocks, multi-session waits, logging and terminal interaction."
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+  spec.files = Dir[
+    "lib/**/*.rb", "examples/**/*.rb", "examples/**/*.md", "docs/**/*.md",
+    "test/**/*.rb", "test/**/*.sh", "test/**/*.md", "Gemfile", "Rakefile",
+    ".rubocop.yml", "expect-pty.gemspec", "README.md", "LICENSE", "CHANGELOG.md", "script/ci", "script/release.rb"
+  ]
+  spec.require_paths = ["lib"]
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+end

data/lib/expect/configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+class Expect
+  # 集中校验会话配置。类级默认值以冻结快照发布，每个会话再构造独立副本。
+  class Configuration
+    # 会话通过 Forwardable 委托这些属性；to_h 使用同一清单生成配置副本。
+    ATTRIBUTES = %i[
+      timeout write_timeout buffer_limit debug_level raw_pty preserve_buffer
+      log_stdout log_listeners raw_terminal reset_timeout_on_read graceful_close
+    ].freeze
+    # 布尔属性同时提供普通读方法和问号查询，写入统一采用 Ruby 真值规则。
+    PREDICATES = %i[
+      raw_pty? preserve_buffer? log_stdout? log_listeners? raw_terminal?
+      reset_timeout_on_read? graceful_close?
+    ].freeze
+
+    attr_reader :timeout, :write_timeout, :buffer_limit, :debug_level, :raw_pty, :preserve_buffer, :log_stdout,
+                :log_listeners, :raw_terminal, :reset_timeout_on_read, :graceful_close
+
+    # 通过 setter 校验构造参数，确保默认值、构造覆盖和后续赋值遵守同一规则。
+    def initialize(timeout: nil, write_timeout: nil, buffer_limit: nil, debug_level: 0,
+                   raw_pty: false, preserve_buffer: false, log_stdout: false,
+                   log_listeners: true, raw_terminal: true, reset_timeout_on_read: false,
+                   graceful_close: false)
+      self.timeout = timeout
+      self.write_timeout = write_timeout
+      self.buffer_limit = buffer_limit
+      self.debug_level = debug_level
+      self.raw_pty = raw_pty
+      self.preserve_buffer = preserve_buffer
+      self.log_stdout = log_stdout
+      self.log_listeners = log_listeners
+      self.raw_terminal = raw_terminal
+      self.reset_timeout_on_read = reset_timeout_on_read
+      self.graceful_close = graceful_close
+    end
+
+    # 设置匹配等待的默认秒数；nil 表示无限等待，0 表示只轮询现有数据。
+    def timeout=(value)
+      @timeout = Expect.duration(value)
+    end
+
+    # 设置写入背压的等待期限；先转换和校验，失败时保留原配置。
+    def write_timeout=(value)
+      @write_timeout = Expect.duration(value)
+    end
+
+    # 限制接收缓冲保留的尾部字节数；正整数为上限，nil 为无限。
+    def buffer_limit=(value)
+      unless value.nil? || (value.is_a?(Integer) && value.positive?)
+        raise ArgumentError, "buffer_limit must be a positive Integer or nil"
+      end
+
+      @buffer_limit = value
+    end
+
+    # 设置诊断详细程度：0 关闭，1 生命周期与匹配，2 收发内容，3 缓冲内容。
+    def debug_level=(value)
+      unless value.is_a?(Integer) && (0..3).cover?(value)
+        raise ArgumentError, "debug_level must be an Integer between 0 and 3"
+      end
+
+      @debug_level = value
+    end
+
+    # 控制 spawn 前是否将子进程终端设为 raw，关闭回显和换行转换。
+    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，用于构造会话副本或发布下一份默认配置。
+    def to_h
+      ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+    end
+  end
+end

data/lib/expect/engine.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+class Expect
+  # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
+  class Engine
+    # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
+    def initialize(patterns, timeout)
+      @patterns = patterns
+      @sessions = patterns.sessions
+      @timeout = Expect.duration(timeout)
+      @deadline = next_deadline
+      @handled_eof = []
+      @polled = false
+    end
+
+    # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
+    def run
+      @sessions.each { |session| session.__send__(:reset_result) }
+      loop do
+        # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
+        result = if (matched = find_match)
+                   handle_match(*matched)
+                 elsif (session = unhandled_eof)
+                   handle_eof(session)
+                 else
+                   read_next
+                 end
+        return result unless result == :retry
+      end
+    end
+
+    private
+
+    # 按声明组、会话、模式的顺序寻找首个匹配，不按文本中的出现位置重新排序。
+    def find_match
+      @patterns.groups.each do |sessions, patterns|
+        sessions.each do |session|
+          next if @handled_eof.include?(session)
+
+          buffer = session.buffer
+          patterns.each do |pattern|
+            position = pattern.locate(buffer)
+            return [session, pattern, position] if position
+          end
+        end
+      end
+      nil
+    end
+
+    # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
+    def handle_match(session, pattern, position)
+      result = session.__send__(:record_match, pattern, position)
+      action = pattern.call(session)
+      return result unless continuing?(action)
+
+      @deadline = next_deadline if action == CONTINUE
+      # 零宽匹配可能不消费字节，必须在继续回调后检查期限，避免只匹配缓冲而永久空转。
+      return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired?
+
+      :retry
+    end
+
+    # 找出尚未派发 EOF 事件的会话，保证每个源只处理一次结束事件。
+    def unhandled_eof
+      @sessions.find { |session| session.eof? && !@handled_eof.include?(session) }
+    end
+
+    # 将剩余字节交给 EOF 回调；需要继续时等待其他源，全部结束则立即返回。
+    def handle_eof(session)
+      result = session.__send__(:record_eof)
+      @handled_eof << session
+      actions = @patterns.eof_patterns_for(session).map { |pattern| pattern.call(session) }
+      return result unless actions.any? { |action| continuing?(action) }
+
+      @deadline = next_deadline if actions.include?(CONTINUE)
+      @sessions.all? { |candidate| @handled_eof.include?(candidate) } ? result : :retry
+    end
+
+    # 在剩余期限内等待可读 IO；零超时仍允许首次非阻塞轮询，EINTR 重试不重新计时。
+    def read_next
+      return handle_timeout if @polled && expired?
+
+      readers = active_sessions
+      begin
+        # 先标记已轮询；即使 select 连续被信号中断，下一轮也会检查原期限。
+        @polled = true
+        ready = IO.select(readers.map(&:to_io), nil, nil, remaining)
+      rescue Errno::EINTR
+        return :retry
+      rescue IOError, SystemCallError => error
+        return record_error(error)
+      end
+      return handle_timeout unless ready
+
+      read_ready(ready.first, readers)
+    end
+
+    # 每个就绪 IO 读取一次，将异常归属到对应会话；仅显式启用时按接收数据刷新期限。
+    def read_ready(readable, sessions)
+      readable.each do |io|
+        session = sessions.find { |candidate| candidate.to_io.equal?(io) }
+        begin
+          data = session.__send__(:read_available)
+        rescue Errno::EINTR
+          next
+        rescue IOError, SystemCallError => error
+          return session.__send__(:record_error, error)
+        end
+        @deadline = next_deadline if data && session.reset_timeout_on_read?
+      end
+      :retry
+    end
+
+    # 返回本次仍需监听的会话，供读取选择和超时回调使用。
+    def active_sessions = @sessions.reject { |session| @handled_eof.include?(session) }
+    # 只有约定的继续符号会驱动下一轮，普通回调返回值不会改变等待流程。
+    def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
+    # 使用单调时钟计算期限；nil 一直表示无限等待，不受系统时间调整影响。
+    def next_deadline = @timeout && (Expect.monotonic + @timeout)
+    # 计算传给 select 的非负等待秒数，避免计时跨过边界时产生负数。
+    def remaining = @deadline && [@deadline - Expect.monotonic, 0].max
+    # 判断有限期限是否已到达；无限等待不会触发超时。
+    def expired? = @deadline && Expect.monotonic >= @deadline
+
+    # select 失败时无法归属单个源，为本次会话记录同一原始异常并返回首个结果。
+    def record_error(error)
+      @sessions.map { |session| session.__send__(:record_error, error) }.first
+    end
+
+    # 为活跃会话记录超时，回调接收全部活跃源；只有重置计时的继续符号能重新等待。
+    def handle_timeout
+      results = active_sessions.map { |session| session.__send__(:record_error, :timeout) }
+      action = @patterns.timeout_pattern&.call(active_sessions)
+      return results.first unless action == CONTINUE
+
+      @deadline = next_deadline
+      @polled = false
+      :retry
+    end
+  end
+end

data/lib/expect/interconnect.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# 为会话补充人工接管和多路 IO 转接；核心会话定义位于 lib/expect.rb。
+class Expect
+  # 注册字面、正则转义或 :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 = input.is_a?(Expect) ? input : Expect.open(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]
+    # 临时建立“用户输入 -> 子进程 -> 显示输出”的双向连接，原监听关系在 ensure 中恢复。
+    self.listeners = [output]
+    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
+    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
+  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
+
+    period = duration(timeout)
+    deadline = period && (monotonic + period)
+    active = sessions.uniq
+    # buffers 保存尚未转发的字节，histories 保存正则跨读取所需的已转发前缀。
+    # 接管原匹配缓冲时只转发，日志已在实际读取时记录，不能重复写入。
+    buffers = active.to_h { |session| [session, session.clear_buffer] }
+    histories = active.to_h { |session| [session, "".b] }
+    terminal_objects = active.flat_map { |session| [session, *session.listeners] }.uniq
+    saved = []
+    polled = false
+    begin
+      terminal_objects.each do |object|
+        next if object.is_a?(Expect) && !object.raw_terminal?
+
+        io = object.respond_to?(:to_io) ? object.to_io : object
+        next unless io.respond_to?(:tty?) && io.tty?
+        next if saved.any? { |entry| entry.first.equal?(io) }
+
+        # 修改前先保存模式，同一个 IO 对象只保存一次，部分初始化失败也能恢复。
+        saved << [io, io.console_mode]
+        io.raw!
+      end
+
+      loop do
+        active.dup.each do |session|
+          return session unless relay_buffer(session, buffers, histories, final: session.eof?)
+          next unless session.eof?
+
+          # EOF 回调为真才继续监听其他源，当前结束源随后移出 active。
+          callback = session.__send__(:sequences)[:eof]
+          return session unless callback&.call
+
+          active.delete(session)
+        end
+        return nil if active.empty?
+
+        remaining = deadline && [deadline - monotonic, 0].max
+        ready = polled && remaining&.zero? ? nil : IO.select(active.map(&:to_io), nil, nil, remaining)
+        polled = true
+        unless ready
+          # 到期后不会再等转义的后半段，将暂存的字面前缀作为普通输入转发。
+          buffers.each do |session, buffer|
+            session.__send__(:propagate, buffer) unless buffer.empty?
+            buffer.clear
+          end
+          return nil
+        end
+        ready[0].each do |io|
+          session = active.find { |candidate| candidate.to_io.equal?(io) }
+          data = session.__send__(:read_available, propagate: false, accumulate: false)
+          buffers[session] << data if data
+        end
+      end
+    ensure
+      # 转义后的尾部归下次 expect/interact 使用；无论正常返回还是异常，都归还缓冲并恢复终端。
+      buffers.each { |session, buffer| session.buffer = buffer + session.buffer }
+      saved.reverse_each { |io, mode| io.console_mode = mode unless io.closed? }
+    end
+  end
+
+  # 转发一个会话的待处理缓冲并剔除转义；返回 false 表示应结束整个转接。
+  # 字面序列暂存潜在前缀，正则序列结合历史匹配；final 为真时不再等待后续字节。
+  def self.relay_buffer(session, buffers, histories, final: false)
+    buffer = buffers.fetch(session)
+    history = histories.fetch(session)
+    sequences = session.__send__(:sequences).except(:eof)
+    loop do
+      matches = sequences.filter_map do |key, handler|
+        if key.is_a?(Regexp)
+          position = Pattern.new(value: key).locate(history + buffer)
+          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
+        session.__send__(:propagate, buffer.byteslice(0, position)) if position.positive?
+        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
+      session.__send__(:propagate, buffer.byteslice(0, count)) if count.positive?
+      if sequences.keys.any?(Regexp)
+        history << buffer.byteslice(0, count)
+        limit = session.buffer_limit
+        history.replace(history.byteslice(-limit, limit)) if limit && history.bytesize > limit
+      end
+      buffer.replace(held.zero? ? "".b : buffer.byteslice(-held, held))
+      return true
+    end
+  end
+  private_class_method :relay_buffer
+
+  protected
+
+  # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
+  attr_accessor :sequences
+end