expect-pty 0.5.3 → 0.6.1

data/test/script_logging_test.rb

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "test_helper"
-require_relative "support/script_probe"
-require "etc"
-
-class ScriptLoggingTest < ExpectTest
-  def shell_probe
-    session = Expect.spawn("/bin/sh", "-i", env: { "PS1" => ScriptProbe::PROMPT, "ENV" => nil, "LC_ALL" => "C" },
-                                            raw_pty: true, log_stdout: false, write_timeout: 3)
-    @sessions << session
-    ScriptProbe::Runner.new(session).ready!
-  end
-
-  def test_multiple_script_files_with_persisted_log_and_shutdown_drain
-    runner = shell_probe
-    Dir.mktmpdir do |dir|
-      report = ScriptProbe.verify_file_session(runner, File.join(dir, "session.log"), user: Etc.getpwuid.name)
-      assert_equal([0, 0, 0, 7, 0, 0, 0], report[:cases].map { |result| result[:status] })
-      assert(report[:cases].all? { |result| result[:passed] })
-      assert_operator report[:log_bytes], :>, 500
-      assert_equal 10, report[:checks].length
-    end
-  end
-
-  def test_callback_log_records_multiple_scripts_exactly_once
-    runner = shell_probe
-    chunks = []
-    runner.session.log_to(->(bytes) { chunks << bytes.dup })
-    %w[first second].each do |value|
-      runner.run(value, "printf '#{value}\\n'\n", expected_status: 0, expected_output: "#{value}\n")
-    end
-    runner.finish!
-    log = ScriptProbe.normalize(chunks.join)
-    assert_equal 1, log.scan(/^first$/).length
-    assert_equal 1, log.scan(/^second$/).length
-    assert_operator log.index("[SEND] first"), :<, log.index("[SEND] second")
-    assert_includes log, "SESSION_FINAL_TAIL\n"
-  end
-
-  def test_borrowed_log_is_flushed_and_stays_open_after_multiple_scripts
-    runner = shell_probe
-    Tempfile.create("expect-borrowed-log") do |file|
-      runner.session.log_to(file)
-      runner.run("one", "printf 'BORROWED_ONE\\n'", expected_status: 0, expected_output: "BORROWED_ONE\n")
-      assert_includes File.binread(file.path), "BORROWED_ONE\n"
-      runner.run("two", "printf 'BORROWED_TWO\\n'", expected_status: 0, expected_output: "BORROWED_TWO\n")
-      runner.finish!
-      refute file.closed?
-      text = File.binread(file.path)
-      assert_includes text, "BORROWED_TWO\n"
-      assert_includes text, "SESSION_FINAL_TAIL\n"
-    end
-  end
-
-  def test_nonzero_exit_is_reported_even_when_expected_text_appears
-    runner = shell_probe
-    failure = assert_raises(ScriptProbe::Failure) do
-      runner.run("bad_status", "printf 'looks good\\n'; exit 9", expected_status: 0, expected_output: "looks good\n")
-    end
-    assert_match(/exit 9, expected 0/, failure.message)
-    refute runner.results.last[:passed]
-    result = runner.run("after_failure", "printf 'still alive\\n'", expected_status: 0,
-                                                                    expected_output: "still alive\n")
-    assert result[:passed]
-  end
-
-  def test_matching_output_is_required_even_with_zero_exit_status
-    runner = shell_probe
-    assert_raises(ScriptProbe::Failure) do
-      runner.run("wrong_output", "printf 'actual\\n'", expected_status: 0, expected_output: "expected\n")
-    end
-    refute runner.results.last[:passed]
-  end
-
-  def test_script_arguments_preserve_quotes_and_shell_metacharacters
-    runner = shell_probe
-    result = runner.run("quoting", "printf '%s\\n' \"a'b\" '$(not-a-command)' 'semi;colon'\n",
-                        expected_status: 0, expected_output: "a'b\n$(not-a-command)\nsemi;colon\n")
-    assert result[:passed]
-  end
-
-  def test_crlf_terminal_output_preserves_exact_script_boundaries
-    runner = shell_probe
-    runner.session.write("stty opost onlcr\n")
-    assert_equal 1, runner.session.expect(ScriptProbe::PROMPT, timeout: 2)
-    ["", "line\n", "no final newline", "two\n\n"].each do |output|
-      result = runner.run("crlf", "printf %s #{Shellwords.escape(output)}",
-                          expected_status: 0, expected_output: output)
-      assert_equal output, result[:output]
-    end
-  end
-
-  def test_logger_error_is_visible_to_caller
-    runner = shell_probe
-    runner.session.log_to(->(_) { raise IOError, "log destination failed" })
-    error = assert_raises(IOError) do
-      runner.run("logger_failure", "printf 'output\\n'", expected_status: 0, expected_output: "output\n")
-    end
-    assert_equal "log destination failed", error.message
-    assert_empty runner.results
-  end
-
-  def test_timeout_preserves_log_and_subsequent_output_is_captured
-    runner = shell_probe
-    session = runner.session
-    Dir.mktmpdir do |dir|
-      path = File.join(dir, "timeout.log")
-      session.log_to(path, mode: "w")
-      session.write("printf 'BEFORE_TIMEOUT\\n'; sleep 0.15; printf 'AFTER_TIMEOUT\\n'\n")
-      assert_equal 1, session.expect("BEFORE_TIMEOUT\n", timeout: 2)
-      assert_nil session.expect("AFTER_TIMEOUT", timeout: 0.02)
-      assert_equal :timeout, session.error
-      assert_includes File.binread(path), "BEFORE_TIMEOUT\n"
-      assert_equal 1, session.expect("AFTER_TIMEOUT\n", timeout: 2)
-      assert_equal 1, session.expect(ScriptProbe::PROMPT, timeout: 2)
-      runner.finish!
-      text = File.binread(path)
-      assert_equal 1, text.scan("BEFORE_TIMEOUT\n").length
-      assert_equal 1, text.scan("AFTER_TIMEOUT\n").length
-      assert_includes text, "SESSION_FINAL_TAIL\n"
-    end
-  end
-end

data/test/support/interact_probe.rb

@@ -1,125 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "script_probe"
-
-module InteractProbe
-  ESCAPE = "\x1d".b.freeze
-  TAIL = "LOCAL_ONLY_TAIL".b.freeze
-
-  def self.configuration(session)
-    state = session.stty
-    return state unless RUBY_PLATFORM.include?("darwin")
-
-    # PENDIN is a transient Darwin kernel state, not a termios configuration.
-    state.sub(/lflag=([0-9a-f]+)/) { "lflag=#{(Regexp.last_match(1).to_i(16) & ~0x20000000).to_s(16)}" }
-  end
-
-  def self.settings(session)
-    [session.listeners, session.log_stdout, session.log_listeners, session.raw_terminal?,
-     session.instance_variable_get(:@sequences).dup]
-  end
-
-  def self.prepare(session, echo: false)
-    # The remote tty needs ISIG for Ctrl-C to reach its foreground process.
-    # Manual interaction needs remote echo because the local input is raw.
-    session.write("stty sane #{echo ? "echo" : "-echo"}; set +o emacs; set +o vi\n")
-    ScriptProbe.check(session.expect(ScriptProbe::PROMPT, timeout: 5), "terminal setup did not return to shell")
-    session.clear_buffer
-  end
-
-  # A real local terminal slave is passed to interact; its master acts as a
-  # keyboard/screen. Only interact reads the remote session during handoff.
-  def self.verify(session, user:)
-    master, slave = PTY.open
-    source = Expect.open(slave)
-    screen = Expect.open(master, write_timeout: 3)
-    source.on_sequence("ORIGINAL_ESCAPE") { false }
-    source.log_listeners = false
-    source.log_stdout = false
-    terminal_state = configuration(source)
-    remote_state = configuration(session)
-    source_settings = settings(source)
-    remote_settings = settings(session)
-    results = []
-    checks = []
-
-    run_cycle = lambda do |number, &actions|
-      nonce = SecureRandom.hex(8)
-      marker = "HANDOFF_#{nonce}"
-      session.write("printf '\\n%s%s\\n' 'HANDOFF_' '#{nonce}'\n")
-      worker = Thread.new do
-        ScriptProbe.check(screen.expect(/#{Regexp.escape(marker)}\r?\n/, timeout: 5),
-                          "handoff output did not reach local terminal")
-        ScriptProbe.check(screen.expect(ScriptProbe::PROMPT, timeout: 5), "handoff prompt missing")
-        ScriptProbe.check(!slave.echo?, "local input terminal did not disable echo")
-        runner = ScriptProbe::Runner.new(screen)
-        actions.call(runner)
-        screen.write(ESCAPE + TAIL)
-        runner.results
-      rescue Exception # rubocop:disable Lint/RescueException -- Clean up terminal drivers even on Interrupt or SystemExit.
-        begin
-          screen.write(ESCAPE)
-        rescue StandardError
-          nil
-        end
-        raise
-      end
-      worker.report_on_exception = false
-      begin
-        returned = session.interact(input: source, escape: ESCAPE, output: slave, timeout: 20)
-        ScriptProbe.check(worker.join(2), "keyboard driver did not finish")
-        results.concat(worker.value)
-        ScriptProbe.check(returned.equal?(source), "interact did not return on the local escape")
-        ScriptProbe.check(source.clear_buffer == TAIL, "escape tail was lost or forwarded to remote")
-        ScriptProbe.check(session.alive?, "local escape closed the remote process")
-        ScriptProbe.check(configuration(source) == terminal_state, "local terminal settings were not restored")
-        ScriptProbe.check(configuration(session) == remote_state,
-                          "remote transport terminal settings were not restored")
-        ScriptProbe.check(settings(source) == source_settings, "local groups/flags/escape handlers were not restored")
-        ScriptProbe.check(settings(session) == remote_settings, "remote groups/flags/escape handlers were not restored")
-        checks << "cycle_#{number}_escape_tail_and_restore"
-      ensure
-        worker.kill.join if worker.alive?
-      end
-    end
-
-    run_cycle.call(1) do |runner|
-      runner.run("interactive_identity", "printf 'USER='; id -un; test -t 0 && printf 'TTY_OK\\n'",
-                 expected_status: 0, expected_output: "USER=#{user}\nTTY_OK\n")
-      runner.run_file(
-        File.join(ScriptProbe::FIXTURES, "02_output.sh"),
-        expected_status: 0,
-        expected_output: "STDOUT_FIRST\nSTDERR_SECOND\n中文输出：日志验证\nSTDOUT_LAST\n"
-      )
-      nonce = SecureRandom.hex(8)
-      # An actual foreground shell handles the forwarded Ctrl-C. Readiness is
-      # acknowledged before sending the control byte, without a timing guess.
-      script = "trap 'printf \"INT_HANDLED_#{nonce}\\n\"; exit 0' INT; " \
-               "printf 'INT_READY_#{nonce}\\n'; while :; do sleep 1; done"
-      screen.write("/bin/sh -c #{Shellwords.escape(script)}\n")
-      ScriptProbe.check(screen.expect(/INT_READY_#{nonce}\r?\n/, timeout: 5), "foreground command did not become ready")
-      screen.write("\x03")
-      ScriptProbe.check(screen.expect(/INT_HANDLED_#{nonce}\r?\n/, timeout: 5),
-                        "Ctrl-C did not reach remote foreground process")
-      ScriptProbe.check(screen.expect(ScriptProbe::PROMPT, timeout: 5), "shell did not recover after Ctrl-C")
-      checks << "ctrl_c_forwarded_to_remote"
-    end
-
-    resumed = ScriptProbe::Runner.new(session)
-    resumed.run("expect_after_interact", "printf 'AUTOMATION_RESUMED\\n'", expected_status: 0,
-                                                                           expected_output: "AUTOMATION_RESUMED\n")
-    results.concat(resumed.results)
-    run_cycle.call(2) do |runner|
-      runner.run("interact_again", "printf 'SECOND_HANDOFF_OK\\n'", expected_status: 0,
-                                                                    expected_output: "SECOND_HANDOFF_OK\n")
-    end
-    checks.push("keyboard_to_remote", "remote_to_screen", "utf8_stdout_stderr",
-                "raw_mode_during_interact", "expect_resume", "reenter_interact")
-    { cases: results, checks: checks,
-      local_tty: slave.path, local_terminal_restored: true, transport_terminal_restored: true }
-  ensure
-    source&.close
-    screen&.close
-    [master, slave].compact.each { |io| io.close unless io.closed? }
-  end
-end

data/test/support/kibitz_probe.rb

@@ -1,177 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "interact_probe"
-
-# Drive the actual host and join CLIs through two independent local terminals.
-# No Minitest dependency, SSH service, password, or external user is needed.
-module KibitzProbe
-  EXAMPLE = File.expand_path("../../examples/kibitz/kibitz.rb", __dir__)
-
-  class Pair
-    attr_reader :host, :guest, :socket_path, :log_path
-
-    def initialize(directory, noproc: false, host_flags: [], guest_flags: [])
-      @sessions = []
-      @terminal_modes = {}
-      @log_path = File.join(directory, "session.log")
-      command = noproc ? ["--noproc"] : ["--", "env", "ENV=", "PS1=#{ScriptProbe::PROMPT}", "LC_ALL=C", "/bin/sh", "-i"]
-      @host = spawn_cli("--timeout", "15", "--log", log_path, *host_flags, *command)
-      invitation = host.expect_result(%r{--join (/tmp/expect-kibitz-[^\r\n ]+/peer\.sock)}, timeout: 5)
-      ScriptProbe.check(invitation.matched?, "host did not print the join command")
-      @socket_path = invitation.captures.first
-      ScriptProbe.check(File.stat(File.dirname(socket_path)).mode & 0o777 == 0o700, "socket directory is not private")
-      ScriptProbe.check(File.stat(socket_path).mode & 0o777 == 0o600, "socket is not private")
-      @guest = spawn_cli("--join", socket_path, "--timeout", "15", *guest_flags)
-      [host, guest].each { |terminal| expect(terminal, /Kibitz connected\.[^\r\n]*\r?\n/) }
-      ScriptProbe.check(!host.to_io.echo? && !guest.to_io.echo?, "connected banner preceded terminal readiness")
-    rescue Exception # rubocop:disable Lint/RescueException -- Clean up terminal drivers even on Interrupt or SystemExit.
-      close
-      raise
-    end
-
-    def spawn_cli(*)
-      terminal = Expect.new(log_stdout: false, write_timeout: 3)
-      @sessions << terminal
-      @terminal_modes[terminal] = InteractProbe.configuration(terminal)
-      terminal.spawn(RbConfig.ruby, EXAMPLE, *)
-      terminal
-    end
-
-    def expect(terminal, pattern)
-      result = terminal.expect_result(pattern, timeout: 5)
-      ScriptProbe.check(result.matched?,
-                        "#{terminal.equal?(host) ? "host" : "guest"} missing #{pattern.inspect} (#{result.error})")
-      result
-    end
-
-    def both(pattern)
-      [host, guest].map { |terminal| expect(terminal, pattern) }
-    end
-
-    def prepare_shell
-      ScriptProbe::Runner.new(host).ready!
-      host.write("printf '\\n%s%s\\n' 'KIBITZ_' 'READY'\n")
-      both(/\r?\nKIBITZ_READY\r?\n/)
-      both(ScriptProbe::PROMPT)
-    end
-
-    def command(terminal, command, output)
-      terminal.write(command, "\n")
-      both(output)
-      both(ScriptProbe::PROMPT)
-    end
-
-    def finish!(expected_host_status: 0)
-      [host, guest].each do |terminal|
-        result = terminal.expect_result(:eof, timeout: 5)
-        ScriptProbe.check(result.eof?, "kibitz did not reach EOF")
-        status = terminal.wait(timeout: 2)
-        expected = terminal.equal?(host) ? expected_host_status : 0
-        ScriptProbe.check(status && status.exitstatus == expected,
-                          "kibitz exit status was #{status&.exitstatus.inspect}, expected #{expected}")
-        ScriptProbe.check(InteractProbe.configuration(terminal) == @terminal_modes.fetch(terminal),
-                          "terminal mode was not restored")
-      end
-      ScriptProbe.check(!File.exist?(File.dirname(socket_path)), "socket directory was not cleaned up")
-      ScriptProbe.check(File.stat(log_path).mode & 0o777 == 0o600, "log permissions changed")
-      self
-    end
-
-    def close
-      @sessions&.reverse_each(&:close)
-    end
-  end
-
-  def self.shared_shell(directory)
-    pair = Pair.new(directory)
-    # With local terminals raw, the process's terminal supplies typed echo.
-    pair.both(ScriptProbe::PROMPT)
-    pair.host.write("printf 'VISIBLE_TYPING\\n'")
-    pair.both("printf 'VISIBLE_TYPING\\n'")
-    pair.host.write("\n")
-    pair.both(/\r?\nVISIBLE_TYPING\r?\n/)
-    pair.both(ScriptProbe::PROMPT)
-    # ready! expects an outstanding prompt; use a fresh one after the echo check.
-    pair.host.write("\n")
-    pair.prepare_shell
-    pair.command(pair.host, "shared_value=42; printf 'HOST_SET\\n'", /HOST_SET\r?\n/)
-    pair.command(pair.guest, "printf 'SHARED=%s\\n' \"$shared_value\"", /SHARED=42\r?\n/)
-    pair.command(pair.guest, "printf '中文输出\\n'; printf 'GUEST_STDERR\\n' >&2", /中文输出\r?\nGUEST_STDERR\r?\n/)
-    pair.command(pair.host, "/bin/sh -c 'exit 7'; printf 'RECOVERED=%s\\n' \"$?\"", /RECOVERED=7\r?\n/)
-    script = "trap 'printf \"INT_HANDLED\\n\"; exit 0' INT; printf 'INT_READY\\n'; while :; do sleep 1; done"
-    pair.host.write("/bin/sh -c #{Shellwords.escape(script)}\n")
-    pair.both(/INT_READY\r?\n/)
-    pair.guest.write("\x03")
-    pair.both(/INT_HANDLED\r?\n/)
-    pair.both(ScriptProbe::PROMPT)
-    pair.guest.write("printf 'FINAL_TAIL\\n'; exit 0\n")
-    pair.both(/FINAL_TAIL\r?\n/)
-    pair.finish!
-    log = ScriptProbe.normalize(File.binread(pair.log_path))
-    %w[HOST_SET SHARED=42 GUEST_STDERR RECOVERED=7 INT_READY INT_HANDLED FINAL_TAIL].each do |line|
-      # With echo disabled the output can follow a prompt on the same line.
-      ScriptProbe.check(log.scan("#{line}\n").length == 1, "#{line} missing or duplicated in log")
-    end
-    { name: "shared_shell", passed: true,
-      checks: %w[visible_typing both_keyboards shared_shell_state broadcast_stdout_stderr utf8 nonzero_recovery
-                 guest_ctrl_c process_eof final_tail unique_log terminal_restore socket_cleanup] }
-  ensure
-    pair&.close
-  end
-
-  def self.direct(directory, ending: :host)
-    custom = ending == :host ? ["--escape", "STOP"] : []
-    pair = Pair.new(directory, noproc: true, host_flags: custom)
-    pair.host.write("HOST_MESSAGE")
-    pair.expect(pair.guest, "HOST_MESSAGE")
-    ScriptProbe.check(pair.host.expect("HOST_MESSAGE", timeout: 0.02).nil?, "noproc echoed the sender's input")
-    pair.guest.write("中文回信")
-    pair.expect(pair.host, "中文回信")
-    ScriptProbe.check(pair.guest.expect("中文回信", timeout: 0.02).nil?, "noproc echoed the guest's input")
-    if ending == :host
-      pair.host.write("prefixST")
-      pair.expect(pair.guest, "prefix")
-      ScriptProbe.check(pair.guest.expect("ST", timeout: 0.02).nil?, "split escape prefix leaked to peer")
-      pair.host.write("OPLOCAL_TAIL")
-    else
-      pair.guest.write(InteractProbe::ESCAPE)
-    end
-    pair.finish!
-    ScriptProbe.check(!pair.guest.before.include?("LOCAL_TAIL") && !pair.guest.before.include?("STOP"),
-                      "local escape leaked to peer")
-    { name: "noproc_#{ending}_escape", passed: true,
-      checks: %w[two_way_bytes utf8 no_local_echo escape peer_eof terminal_restore socket_cleanup] }
-  ensure
-    pair&.close
-  end
-
-  def self.noescape(directory)
-    pair = Pair.new(directory, noproc: true, host_flags: ["--noescape"])
-    pair.host.write("before\x1dafter")
-    pair.expect(pair.guest, "before\x1dafter")
-    pair.guest.write(InteractProbe::ESCAPE)
-    pair.finish!
-    { name: "noescape", passed: true, checks: %w[control_byte_forwarded peer_eof terminal_restore socket_cleanup] }
-  ensure
-    pair&.close
-  end
-
-  def self.process_failure(directory)
-    pair = Pair.new(directory)
-    pair.prepare_shell
-    pair.host.write("exit 7\n")
-    pair.finish!(expected_host_status: 7)
-    { name: "process_failure", passed: true, checks: %w[nonzero_exit_status peer_eof terminal_restore socket_cleanup] }
-  ensure
-    pair&.close
-  end
-
-  def self.relay_timeout(directory)
-    pair = Pair.new(directory, noproc: true, host_flags: ["--timeout", "1"])
-    pair.finish!(expected_host_status: 1)
-    ScriptProbe.check(pair.host.before.include?("Kibitz ended (timeout)."), "relay did not report its timeout")
-    { name: "relay_timeout", passed: true, checks: %w[timeout_status peer_eof terminal_restore socket_cleanup] }
-  ensure
-    pair&.close
-  end
-end

data/test/support/script_probe.rb

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require "securerandom"
-require "shellwords"
-require_relative "../../lib/expect/pty"
-
-# Shared by the real SSH check and the automatic local-PTY tests. This is a
-# test harness for a POSIX shell, not a network-device command abstraction.
-module ScriptProbe
-  PROMPT = "EXPECT_SCRIPT_PROMPT> "
-  FIXTURES = File.expand_path("../fixtures/ssh_scripts", __dir__)
-
-  class Failure < StandardError; end
-
-  def self.check(condition, message)
-    raise Failure, message unless condition
-  end
-
-  def self.normalize(bytes)
-    bytes.gsub("\r\n", "\n").b
-  end
-
-  class Runner
-    attr_reader :session, :results
-
-    def initialize(session, timeout: 5)
-      @session = session
-      @timeout = timeout
-      @results = []
-    end
-
-    def ready!
-      result = session.expect_result(PROMPT, timeout: @timeout)
-      ScriptProbe.check(result.matched?, "shell prompt missing (#{result.error})")
-      # Avoid terminal echo being mistaken for script output or leaking the
-      # test's wrapper command into the output we verify.
-      # Interactive shells may interpret high-bit bytes as readline commands
-      # in a C locale. Disable editing for literal script transmission.
-      session.write("stty -echo; set +o emacs; set +o vi\n")
-      result = session.expect_result(PROMPT, timeout: @timeout)
-      ScriptProbe.check(result.matched?, "shell setup failed (#{result.error})")
-      session.clear_buffer
-      self
-    end
-
-    def run_file(path, expected_status:, expected_output:)
-      run(File.basename(path), File.binread(path), expected_status: expected_status, expected_output: expected_output)
-    end
-
-    def run(name, script, expected_status:, expected_output:)
-      nonce = SecureRandom.hex(12)
-      start_marker = "PROBE_BEGIN_#{nonce}"
-      end_marker = "PROBE_END_#{nonce}"
-      digest = Digest::SHA256.hexdigest(script)
-      # Quote once for the remote shell without inserting backslashes between
-      # UTF-8 bytes (File.binread returns an ASCII-8BIT string).
-      quoted_script = "'#{script.gsub("'", %q('"'"'))}'"
-      # Inputs are logged deliberately as metadata: Expect's automatic log
-      # records received bytes, not sends. Never include authentication here.
-      session.write_log("\n[SEND] #{name} sha256=#{digest}\n")
-      command = "printf '\\n%s%s\\n' 'PROBE_BEGIN_' '#{nonce}'; " \
-                "/bin/sh -c #{quoted_script}; probe_status=$?; " \
-                "printf '\\n%s%s:%s\\n' 'PROBE_END_' '#{nonce}' \"$probe_status\"\n"
-      session.write(command)
-      started = session.expect_result(/(?:\A|\r?\n)#{Regexp.escape(start_marker)}\r?\n/, timeout: @timeout)
-      ScriptProbe.check(started.matched?, "#{name}: begin marker missing (#{started.error})")
-      ended = session.expect_result(/(?:\A|\r?\n)#{Regexp.escape(end_marker)}:(\d+)\r?\n/, timeout: @timeout)
-      ScriptProbe.check(ended.matched?, "#{name}: script did not finish (#{ended.error})")
-      output = ScriptProbe.normalize(ended.before)
-      status = Integer(ended.captures.fetch(0), 10)
-      # Wait for the shell before starting another script, including when the
-      # prior script exited nonzero. Each script runs in its own subshell.
-      prompt = session.expect_result(PROMPT, timeout: @timeout)
-      ScriptProbe.check(prompt.matched?, "#{name}: shell did not recover (#{prompt.error})")
-      session.write_log("\n[EXIT] #{name} status=#{status}\n")
-      passed = status == expected_status && output == expected_output.b
-      result = { name: name, sha256: digest, status: status, expected_status: expected_status,
-                 output: output.dup.force_encoding(Encoding::UTF_8), passed: passed }
-      results << result
-      ScriptProbe.check(status == expected_status, "#{name}: exit #{status}, expected #{expected_status}")
-      ScriptProbe.check(output == expected_output.b, "#{name}: output differs from fixture expectation")
-      result
-    end
-
-    def finish!
-      # The last bytes arrive while soft_close drains the session. No expect
-      # call is made after this send, so the log proves shutdown draining.
-      session.write("sleep 0.1; printf '%s%s\\n' 'SESSION_' 'FINAL_TAIL'; exit 0\n")
-      session.soft_close(timeout: 3)
-      ScriptProbe.check(session.closed? && session.exit_code&.zero?, "shell did not exit cleanly")
-    end
-  end
-
-  # Run all script fixtures in one session, then verify the persisted log.
-  # An explicit nonzero fixture is an expected success of the test harness.
-  def self.verify_file_session(runner, path, user:)
-    session = runner.session
-    # With SSH, the remote TTY differs from the local PTY. Obtain it using an
-    # independent command, then demand an exact identity fixture response.
-    session.write("printf '\\n%s' 'TTY_PROBE='; tty\n")
-    tty = session.expect_result(%r{(?:\A|\n)TTY_PROBE=(/dev/[^\r\n]+)\r?\n}, timeout: 5)
-    check(tty.matched?, "remote TTY probe failed")
-    terminal = tty.captures.fetch(0)
-    check(session.expect(PROMPT, timeout: 5), "TTY probe did not return to shell")
-
-    # The caller allocates a fresh private directory; exercise truncation only
-    # on this new test file, never on an existing user's log.
-    File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write("OLD_TEST_CONTENT\n") }
-    log = session.log_to(path, mode: "w")
-    cases = [
-      ["01_identity.sh", 0, "USER=#{user}\nTTY=#{terminal}\nIDENTITY_OK\n"],
-      ["02_output.sh", 0, "STDOUT_FIRST\nSTDERR_SECOND\n中文输出：日志验证\nSTDOUT_LAST\n"],
-      ["03_delayed.sh", 0, "DELAY_BEGIN\nDELAY_MIDDLE\nDELAY_END\n"],
-      ["04_failure.sh", 7, "EXPECTED_FAILURE\n"],
-      ["05_recovery.sh", 0, "RECOVERY_OK\nVALUE=42\n"]
-    ]
-    cases.each do |name, status, output|
-      runner.run_file(File.join(FIXTURES, name), expected_status: status, expected_output: output)
-      # Read while the logger is open to prove writes are immediately visible.
-      live = normalize(File.binread(path))
-      check(live.include?(output.b), "#{name}: live log is missing output")
-      check(live.include?("[EXIT] #{name} status=#{status}\n"), "#{name}: live exit annotation missing")
-    end
-    session.log_output = nil
-    check(log.closed?, "owned log was not closed")
-    before_disabled = File.binread(path)
-    runner.run("logging_disabled", "printf 'UNLOGGED_OUTPUT\\n'\n", expected_status: 0,
-                                                                    expected_output: "UNLOGGED_OUTPUT\n")
-    check(File.binread(path) == before_disabled, "disabled logger still wrote data")
-
-    # The default mode must append, retaining every preceding command.
-    appended = session.log_to(path)
-    runner.run("logging_resumed", "printf 'APPEND_OK\\n'\n", expected_status: 0, expected_output: "APPEND_OK\n")
-    runner.finish!
-    check(appended.closed?, "close did not close the owned log")
-    bytes = File.binread(path)
-    check(bytes.start_with?(before_disabled), "append mode overwrote previous log bytes")
-    text = normalize(bytes)
-    check(!text.include?("OLD_TEST_CONTENT") && !text.include?("UNLOGGED_OUTPUT"),
-          "truncated or disabled data leaked into log")
-    position = -1
-    cases.each do |name, status, output|
-      sent = text.index("[SEND] #{name} ")
-      exited = text.index("[EXIT] #{name} status=#{status}\n")
-      check(sent && exited && sent > position && exited > sent, "#{name}: incorrect log execution order")
-      check(text.scan(Regexp.new(Regexp.escape(output.b), Regexp::NOENCODING)).length == 1,
-            "#{name}: output missing or duplicated")
-      position = exited
-    end
-    check(text.include?("APPEND_OK\n"), "resumed logging lost output")
-    check(text.scan("SESSION_FINAL_TAIL\n").length == 1, "shutdown lost or duplicated final output")
-    { cases: runner.results, remote_tty: terminal, log_bytes: bytes.bytesize,
-      log_sha256: Digest::SHA256.hexdigest(bytes),
-      checks: %w[exact_output execution_order live_flush stdout_stderr utf8 nonzero_recovery
-                 truncate disable append eof_drain] }
-  end
-end