net-connector 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33503c92ccbe8f7000652c0b47b967a8f2f40e6c9edd7081ba305c3246efe820
-  data.tar.gz: f2d4c434caab1b888d1b4cd9bf25a0def4e7e26eb63b2e6e5e93d8b56cc34c0d
+  metadata.gz: 0c8e0db79f9b795cc321cb29571f62e0abd559273b7d09c7598be25eb4141c27
+  data.tar.gz: b96f4f50c83bbc8f94a16b43afcd62eae341380342ce975640e03ddabf42132c
 SHA512:
-  metadata.gz: e8c126666632d1f4a708cbcc42c1df5ad434d37978a55fe2db363e3628f2c7e2779192d05ad7d8989933d389d92a6de520669a93a47c46209816a85d423abcca
-  data.tar.gz: ad704438b1ed05942371fe3f57a7ebf66f563261406682013b18f57c8cfbc8b01a190a41a685a2991f4d53ff3e2912d2cf8c8e272b593bc83e1a439c821ef349
+  metadata.gz: cb6aff24a1892a671e6f6263c6fe1d49894bfdc4748ddd9726db5442bc891cf6fd1bbced58f7fd4d468259e3dd2db88b11e9457f514fb02429061fa6b74bea75
+  data.tar.gz: 468c0dad7b32ee3e1d7f5f7969afecd37a4199d92b117bced55674c748e21fa3550d390427800cbbb8f9c3b0d8ed9008250118c254be54db9d8d24500e572e48

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 更新记录
 
+## Unreleased
+
+## 0.18.0 - 2026-10-23
+
+- Add on_receipt completion callbacks to command, script, save and custom operations, retaining completed responses after later logging, processing, budget or cancellation failures.
+- Retain PTY channels after incomplete cleanup and retry cleanup before reopening or recovering a connection.
+- Use owned Expect session scopes during SSH authentication so initialization cancellation releases terminal handles and cleanup failures preserve the authentication error.
+- Use English diagnostics, CLI help and reports, and consume string-keyed progress documents from Runner 0.2.
+
+## 0.17.2 - 2026-10-23
+
+- Migrate shared CLI entrypoints to ctx_cli 0.2.0 names without legacy aliases.
+- Synchronize new directory ancestry across batch reports and local/SSH archives; synchronize uploaded-file cleanup.
+- Keep host-key comparison and vendor parsing independent of host field separators.
+- Reuse ctx_cli configuration, initialization, terminal and option boundaries without changing backup/TFTP/topology policies.
+
 ## 0.17.1 - 2026-10-22
 
 - Delegate shared configuration, private initialization, option groups and terminal interaction to ctx_cli 0.1.0.

data/docs/architecture.md

@@ -206,8 +206,14 @@ Fleet 可把回执与本地普通文件的时间、稳定性、摘要及目录
 
 提示符和交互标记是 Ruby 正则表达式，应短到能放入未匹配尾部；流式适配器不支持需要无限长历史的模式。收集输出的上限与匹配窗口上限不同。终端渲染器只处理常见行编辑控制符，不是完整屏幕终端模拟器。`Profile#terminal_size` 使用 `[宽, 高]`，PTY 适配器转换为 Ruby 的 `[行, 列]`。
 
+传输关闭先撤下活跃信道，使连接不可用；尚未回收的信道由内部 `@closing_channel` 保留。`hard_close` 正常返回且当前进程拥有的子进程已退出后才释放引用；异常、非局部退出及有界等待后仍存活的子进程都保留清理责任，后者明确报告 IOError。后续 `close` 重试原信道，完成后不重复清理。fork 副本仅关闭继承句柄，不要求回收父进程拥有的子进程。
+
+重新打开会先完成旧资源回收，失败时不创建新进程或 SSH 信任快照。私有 `close_resources` 供关闭与打开共用；公开 `close` 停止日志交付，而打开时保留新连接已配置的日志目标。SSH 临时信任快照仍只处置一次。连接恢复只有在旧传输及日志清理成功后才能替换传输对象；失败仍报告原连接错误，保留旧所有者供后续关闭，不重放设备命令。注入信道工厂须遵守现有 Expect 的 `hard_close` / `alive?` 生命周期协议。
+
 PTY 输出上限直接读取信道公开的 `buffer_bytesize` 标量，避免正常分片反复取得累计正文副本；只有实际超限时才获取错误正文，关闭日志也不会关闭上限检查。传输与 SSH 归档认证统一使用当前 `Session`、`transcript`、`spawn(raw: true)` 和 `expect` 契约，不探测或回退到旧接口。运行要求为 expect-pty 0.9.4+、Ruby 3.4+。
 
+SSH 归档认证借用 `Expect.spawn` 块中交付的私有会话；初始化与交接期间取消的回收责任由 Expect 工厂持有，不在连接器重复构造、登记和 ensure 清理。普通清理错误不能替换认证主异常；没有主异常时仍传播清理错误，新发生的致命清理异常沿用 Expect 契约。密码仍只发送一次，15 秒对话预算、输出隐私及调用方的主连接核对保持原有职责。
+
 `prepare_command` 钩子返回 `Command` 表示继续执行，返回 nil 表示跳过。其他返回值在替代命令发送前以 `ScriptError` 拒绝，保留原脚本位置和此前完成步骤，诊断不展开非法值。钩子内部主动执行的查询仍遵循原有执行与输出预算边界。
 
 `max_script_output_bytes` 为正 Integer 或 nil。计数属于每个 Execution，主命令以及准备、提示符和后处理钩子的 `Execution#execute_command` 共用计数，包含原始分页标记和最终提示符，不能用 `capture: false` 绕过。登录和提权认证保留各自原有单响应上限。每次脚本新建计数器；一次租约中的多个脚本、多个设备和多个批次不共用它。

data/docs/usage.md

@@ -143,6 +143,10 @@ warn "#{result.error.code}: #{result.steps.size} completed commands" if result.f
 
 `execute_command` runs one command; `execute_script` accepts a `Script` or command array. `Script.load(path)` reads a file. Commands are validated before I/O; completed steps survive later failures. `save_config` explicitly sends save commands; ordinary scripts do not save automatically.
 
+Use `on_receipt: ->(step) { ... }` with these methods or `execute_operation` to retain completed responses even when later logging, postprocessing, output-budget checks or cancellation prevent a successful return. It receives each completed `Command::Result` once, before the optional success-progress block. Timeouts and device rejection without a completed step produce no receipt. A receipt confirms the response, not persistence or the intended configuration effect.
+
+The receipt callback runs synchronously within the operation and must not reenter the device. Its exception stops subsequent commands; an earlier failure or cancellation keeps precedence. Step output is unredacted business data, like `Result#steps`; persist protected output or safe summaries. Interruptions still propagate, and a killed process cannot deliver callbacks.
+
 `result.output` concatenates completed steps as raw bytes without transcoding. Each call returns a mutable binary string; changing it does not change the frozen step outputs. Use `result.config` for the cleaned configuration, or `result.value!` to raise on failure before reading the successful value.
 
 Set `max_script_output_bytes:` to bound cumulative raw responses, including additional queries. Default is `nil`. Exceeding it returns `ScriptOutputLimitExceeded` (`:script_output_limit_exceeded`) and stops subsequent commands; the current command may already have executed. `max_output_bytes` separately limits each response. Neither setting is a process-memory limit.

data/docs/usage.zh-CN.md

@@ -186,6 +186,10 @@ end
 
 `execute_command` 执行一条命令；`execute_script` 接收 `Script` 或命令数组；`Script.load(path)` 读取脚本文件。所有命令在设备 I/O 前校验，后续步骤失败时仍保留已完成结果，库不会自动重放命令。`save_config` 显式执行厂商保存命令，普通脚本不会自动保存。
 
+上述方法及 `execute_operation` 接受 `on_receipt: ->(step) { ... }`，用于固定已收到的完整响应：即使之后的日志、后处理、累计输出检查或取消阻止方法正常返回，已完成的 `Command::Result` 仍交付一次，早于可选的成功进度块。没有完成步骤的超时或设备拒绝不产生回执；回执本身不证明设备保存或预期配置生效。
+
+回执回调在操作中同步执行，不得重入设备。回调异常停止后续命令，已有主故障或取消保持优先。步骤正文与 `Result#steps` 一样未脱敏，宿主应保护正文或仅保存安全摘要。取消异常仍继续传播，进程被强制终止时无法保证回调交付。
+
 `result.output` 按顺序拼接已完成步骤的原始字节，不执行字符编码转换。每次调用返回可修改的二进制字符串，修改它不会改变已冻结的步骤输出。清理后的配置使用 `result.config`；需要失败时先抛出错误，再读取成功值时使用 `result.value!`。
 
 创建连接器时可设置 `max_script_output_bytes: 8 * 1024 * 1024`，限制每个脚本及其追加查询累计收到的原始响应字节；默认 `nil` 保持原有完整输出行为。达到上限后不再发送下一命令，当前响应超过上限时保留刚完成的步骤并返回 `ScriptOutputLimitExceeded`（`code: :script_output_limit_exceeded`）。命令可能已经执行，不会自动重试。原有 `max_output_bytes` 继续限制单次读取响应；累计预算不是进程内存上限，详细计数规则见架构文档。

data/lib/net/connector/collect/progress.rb

@@ -23,46 +23,46 @@ module Net
           status = result_status(result)
           code = diagnostic_code(result)
           message = case status
-                    when :complete then "采集完成；报告已保存"
-                    when :partial then "部分成功（#{code}）"
-                    else "未完成（#{code}）"
+                    when "complete" then "Collection complete; reports saved"
+                    when "partial" then "Partially complete (#{code})"
+                    else "Incomplete (#{code})"
                     end
-          super(host: result.fetch(:device).fetch("host"), success: status == :complete,
-                duration_ms: result.fetch(:duration_ms), message: message, error_code: code)
+          super(host: result.fetch("device").fetch("host"), success: status == "complete",
+                duration_ms: result.fetch("duration_ms"), message: message, error_code: code&.to_sym)
         end
 
         # 使用持久化摘要作最终判定，不把已处理数量或完整性当作健康结论。
         def finish(summary)
-          results = summary.fetch(:devices)
+          results = summary.fetch("devices")
           counts = results.group_by { |result| result_status(result) }.transform_values(&:size)
-          failures = results.reject { |result| result_status(result) == :complete }
+          failures = results.reject { |result| result_status(result) == "complete" }
                             .group_by { |result| diagnostic_code(result) }.transform_values(&:size)
-          super(success: summary.fetch(:status) == :complete, succeeded: counts.fetch(:complete, 0),
-                partial: counts.fetch(:partial, 0), failed: counts.fetch(:failed, 0), skipped: @skipped || 0, failures: failures)
-          pending = summary.fetch(:pending).size
-          notice("未采集 #{pending} 台；详见批次报告") if pending.positive?
-          notice("证据完整性不代表网络健康，审查结果见报告。")
-          location(File.join(summary.fetch(:directory), "summary.json"))
-          location(File.join(summary.fetch(:directory), "summary.txt"), label: "文本报告")
+          super(success: summary.fetch("status") == "complete", succeeded: counts.fetch("complete", 0),
+                partial: counts.fetch("partial", 0), failed: counts.fetch("failed", 0), skipped: @skipped || 0, failures: failures)
+          pending = summary.fetch("pending").size
+          notice("Not collected: #{pending} devices; see the batch report") if pending.positive?
+          notice("Complete evidence does not establish network health; see the review results in the report.")
+          location(File.join(summary.fetch("directory"), "summary.json"))
+          location(File.join(summary.fetch("directory"), "summary.txt"), label: "Text report")
         end
 
         private
 
         # 写入失败的完整快照仍是未交付结果，不能在终端宣称成功。
         def result_status(result)
-          return :failed unless result[:report_saved] == true
+          return "failed" unless result["report_saved"] == true
 
-          %i[complete partial].include?(result[:status]) ? result[:status] : :failed
+          %w[complete partial].include?(result["status"]) ? result["status"] : "failed"
         end
 
         # 完整维度的提示不属于失败；优先保留会话错误，再选择未完成维度的诊断码。
         def diagnostic_code(result)
-          return :report_not_saved unless result[:report_saved] == true
-          return nil if result[:status] == :complete
-          return result[:error] if result[:error]
+          return "report_not_saved" unless result["report_saved"] == true
+          return nil if result["status"] == "complete"
+          return result["error"] if result["error"]
 
-          dimensions = result.fetch(:dimensions, {}).values.reject { |dimension| dimension[:status] == :complete }
-          dimensions.flat_map { |dimension| dimension.fetch(:issues, []) }.first || :collection_incomplete
+          dimensions = result.fetch("dimensions", {}).values.reject { |dimension| dimension["status"] == "complete" }
+          dimensions.flat_map { |dimension| dimension.fetch("issues", []) }.first || "collection_incomplete"
         end
       end
     end

data/lib/net/connector/device/base.rb

@@ -130,23 +130,26 @@ module Net
       def close = @session.close
 
       # 将一条文本命令包装成脚本并执行。
-      def execute_command(text, **, &)
-        execute_script(Script.new([Command.new(text, **)]), &)
+      def execute_command(text, on_receipt: nil, **, &)
+        script = Script.new([Command.new(text, **)])
+        return execute_script(script, &) if on_receipt.nil?
+
+        execute_script(script, on_receipt: on_receipt, &)
       end
 
       # 接收脚本或命令数组，统一交给单次会话执行。
-      def execute_script(script, &)
+      def execute_script(script, on_receipt: nil, &)
         script = Script.new(script) unless script.is_a?(Script)
-        perform_script(script, &)
+        perform_script(script, on_receipt: on_receipt, &)
       end
 
       # 多步骤业务操作独占当前会话，内部脚本仍禁止回调重入。
       def with_operation(name, &) = @session.with_operation(name, &)
 
       # 业务层可扩展脚本准备、响应校验和最终结果，所有钩子均在会话锁内执行。
-      def execute_operation(script, name:, prompt: nil, after_command: nil, privilege: true, &finalize)
+      def execute_operation(script, name:, prompt: nil, after_command: nil, privilege: true, on_receipt: nil, &finalize)
         perform_script(script, operation: name, prompt: prompt, after_command: after_command,
-                       privilege: privilege, finalize: finalize)
+                       privilege: privilege, finalize: finalize, on_receipt: on_receipt)
       end
 
       # 返回已确认的提示，供业务层为只读采集绑定准确的结束条件。
@@ -260,7 +263,8 @@ module Net
 
       # 在会话锁内运行脚本及业务回调，保留已完成步骤和统一错误边界。
       def perform_script(script, operation: nil, prompt: nil, after_command: nil, privilege: true,
-                         finalize: nil, &on_step)
+                         finalize: nil, on_receipt: nil, &on_step)
+        raise ArgumentError, "on_receipt must respond to call" unless on_receipt.nil? || on_receipt.respond_to?(:call)
         return Result.new if script.empty?
 
         execution = build_execution(operation: operation, prompt: prompt, after_command: after_command, privilege: privilege)
@@ -269,7 +273,7 @@ module Net
         @session.perform(:script) do
           @session.log_script(operation: operation, steps: execution.steps) do
             @session.with_sensitive_output(output_sensitive) { before_batch(execution) }
-            result = execution.execute_script(script, &on_step)
+            result = execution.execute_script(script, on_receipt: on_receipt, &on_step)
             sensitive_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
             @session.with_sensitive_output(sensitive_result) do
               result = finalize_script_result(result, finalize)

data/lib/net/connector/device/save_config.rb

@@ -5,13 +5,13 @@ module Net
     # 保存命令及能力入口，响应语义由通用执行器负责。
     module SaveConfig
       # 执行厂商保存配置命令；不支持时返回显式失败结果。
-      def save_config
+      def save_config(on_receipt: nil)
         if save_commands.empty?
           return Result.new(error: @session.build_error(UnsupportedOperation, "saving configuration is not supported",
                                                   phase: :save))
         end
 
-        execute_script(save_commands)
+        on_receipt.nil? ? execute_script(save_commands) : execute_script(save_commands, on_receipt: on_receipt)
       end
 
       # 返回保存配置命令；空数组表示设备不支持保存。

data/lib/net/connector/engine/execution.rb

@@ -28,7 +28,7 @@ module Net
       def sensitive? = @sensitive
 
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
-      def execute_script(script)
+      def execute_script(script, on_receipt: nil)
         script.each do |original_command|
           @session.with_command_redaction(original_command) do
             @current_command = original_command
@@ -39,15 +39,7 @@ module Net
             raise build_error("prepare_command must return a Command or nil") unless command.is_a?(Command)
 
             @current_command = command
-            started = Expect.monotonic
-            step = nil
-            response = execute_command(command) do |received|
-              step = Command::Result.new(command: command, output: received.output, prompt: received.prompt,
-                                       duration: Expect.monotonic - started)
-              steps << step
-            end
-            # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
-            @after_command.call(command, response, self)
+            step = execute_step(command, on_receipt: on_receipt)
             yield step if block_given?
             validate_response_budget!(@last_executed_command)
           rescue => error
@@ -97,6 +89,41 @@ module Net
 
       private
 
+      # 完成回执独立于成功进度；日志、后处理、预算或取消不撤销已收到的响应。
+      def execute_step(command, on_receipt:)
+        started = Expect.monotonic
+        step, failure = nil, nil
+        finished = false
+        begin
+          response = execute_command(command) do |received|
+            step = Command::Result.new(command: command, output: received.output, prompt: received.prompt,
+                                       duration: Expect.monotonic - started)
+            steps << step
+          end
+          @after_command.call(command, response, self)
+          finished = true
+          step
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 完成事实先交付，原始取消随后继续传播。
+          failure = error
+          raise
+        ensure
+          deliver_receipt(step, on_receipt, failure, unwinding: !finished) if step && on_receipt
+        end
+      end
+
+      # 收据处理不能用自身异常替换此前的设备失败或取消，也不自动重复回调。
+      def deliver_receipt(step, callback, failure, unwinding:)
+        callback.call(step)
+      ensure
+        # ensure 覆盖回调内的 throw/kill；不能让二次退出替换外层正在传播的取消。
+        if unwinding
+          raise failure, cause: failure.cause if failure
+
+          # 仅结束这个回调子方法，让 execute_step 原有的非局部退出继续。
+          return # rubocop:disable Lint/EnsureReturn -- 保留调用方正在进行的 throw、return 或线程终止。
+        end
+      end
+
       # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
       def validate_send_budget!(command)
         return unless @output_limit && @output_bytes >= @output_limit

data/lib/net/connector/engine/known_hosts.rb

@@ -159,7 +159,7 @@ module Net
         output, status = Open3.capture2e("ssh-keygen", "-f", path, "-F", @host)
         raise IOError, "reading device host key failed" unless [0, 1].include?(status.exitstatus)
 
-        output.lines("\n").reject { |line| line.start_with?("#") }.map { |line| line.split[1, 2] }.uniq
+        output.lines("\n").reject { |line| line.start_with?("#") }.map { |line| line.split(" ")[1, 2] }.uniq
       end
 
       # 从指定快照中移除当前主机条目，不直接修改共享信任文件。

data/lib/net/connector/engine/log/messages.rb

@@ -11,36 +11,36 @@ module Net
         def format(name, fields)
           case name
           when "connect"
-            "开始连接 #{fields[:host]}（#{fields[:protocol].to_s.upcase}，账号 #{fields[:username]}）"
+            "Connecting to #{fields[:host]}(#{fields[:protocol].to_s.upcase}, user #{fields[:username]})"
           when "connect_failed"
-            "连接失败：#{fields[:message]}（#{fields[:error]}）"
+            "Connection failed: #{fields[:message]}(#{fields[:error]})"
           when "login_start"
-            "等待设备登录提示"
+            "Waiting for the device login prompt"
           when "login_output"
-            "登录过程回显（已脱敏）："
+            "Login output (redacted): "
           when "login_complete"
-            fields[:status] == "ok" ? "登录成功，设备提示符：#{fields[:prompt]}" :
-              "登录失败：#{fields[:message]}（#{fields[:error]}）"
+            fields[:status] == "ok" ? "Login succeeded; device prompt: #{fields[:prompt]}" :
+              "Login failed: #{fields[:message]}(#{fields[:error]})"
           when "command_start"
-            "下发命令：#{fields[:text]}"
+            "Sending command: #{fields[:text]}"
           when "device_output"
-            "设备回显："
+            "Device output: "
           when "command_complete"
-            fields[:status] == "response_received" ? "命令回显结束，已收到设备提示符" :
-              "命令执行失败：#{fields[:message]}（#{fields[:error]}）"
+            fields[:status] == "response_received" ? "Command output complete; device prompt received" :
+              "Command failed: #{fields[:message]}(#{fields[:error]})"
           when "operation_start"
-            "开始处理设备脚本"
+            "Starting device script"
           when "operation_complete"
-            fields[:status] == "completed" ? "设备脚本处理完成" :
-              "设备脚本处理失败：#{fields[:message]}（#{fields[:error]}）"
+            fields[:status] == "completed" ? "Device script complete" :
+              "Device script failed: #{fields[:message]}(#{fields[:error]})"
           when "tftp_backup"
             case fields[:status]
             when "reported_uploaded"
-              "TFTP 备份：设备报告上传成功，目标 #{fields[:server]}/#{fields[:path]}；服务器文件尚未核验"
+              "TFTP backup: device reported a successful upload to #{fields[:server]}/#{fields[:path]}; server file has not been verified"
             when "transfer_failed"
-              "TFTP 备份失败：设备报告传输失败，服务器 #{fields[:server]}"
+              "TFTP backup failed: device reported a transfer failure; server #{fields[:server]}"
             else
-              "TFTP 备份未确认：设备未报告上传成功，服务器 #{fields[:server]}"
+              "TFTP backup unconfirmed: device did not report a successful upload; server #{fields[:server]}"
             end
           else
             name.to_s

data/lib/net/connector/engine/session.rb

@@ -404,8 +404,8 @@ module Net
           failure = normalize_error(error, phase: phase)
           @log.log_failure(phase == :connect ? "connect_failed" : "login_complete", failure,
                            status: "failed", phase: phase, duration_ms: elapsed_ms(started))
-          close_preserving_failure
-          replacement = attempted_recovery ? nil : @recovery.recover(failure, transport)
+          cleaned = close_preserving_failure
+          replacement = cleaned && !attempted_recovery ? @recovery.recover(failure, transport) : nil
           if replacement
             @transport = replacement
             attempted_recovery = true
@@ -458,12 +458,13 @@ module Net
         raise normalize_error(error, phase: :close), cause: nil
       end
 
-      # 尝试清理资源但不覆盖原始操作异常。
+      # 清理结果决定能否移交传输所有权；失败仍保留原操作异常与待清理资源。
       def close_preserving_failure
         close_resources
+        true
       rescue Exception # rubocop:disable Lint/RescueException -- 原操作失败时，清理故障或中断均不得覆盖它。
         # 所有清理路径完成后，原始操作异常仍然是权威结果。
-        nil
+        false
       end
     end
   end

data/lib/net/connector/engine/transports.rb

@@ -21,14 +21,17 @@ module Net
           @configuration = configuration
           @channel_factory = channel_factory
           @terminal_size = terminal_size
+          @channel_owner = Process.pid
         end
 
         # 打开伪终端、设置终端大小并启动设备进程。
         def open
           failure = nil
           configuration.validate_endpoint!
+          close_resources if @channel || @closing_channel
           # 构造期间的阻塞仍可取消；返回交接先登记信道，再交付异步中断。
           Thread.handle_interrupt(Exception => :on_blocking) do
+            @channel_owner = Process.pid
             @channel = if @channel_factory
                          @channel_factory.call
                        else
@@ -89,21 +92,10 @@ module Net
           @log_target = target
         end
 
-        # 清除信道和日志目标，并强制关闭底层进程。
+        # 停止日志交付并关闭信道；失败资源继续由内部账本持有。
         def close
-          failure = nil
-          # 从字段移交到关闭完成期间不能取消，避免丢失尚未回收的进程。
-          Thread.handle_interrupt(Exception => :never) do
-            channel = @channel
-            @channel = nil
-            @log_target = nil
-            channel&.hard_close
-          rescue Exception => error # rubocop:disable Lint/RescueException -- 延迟取消不能覆盖底层关闭的首个故障。
-            failure = error
-            raise
-          end
-        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付时仍保留最先观察到的故障。
-          raise failure || error, cause: nil
+          @log_target = nil
+          close_resources
         end
 
         # 把人工交互结果转换为设备 EOF、超时或输入状态。
@@ -119,6 +111,30 @@ module Net
 
         private
 
+        # 活跃信道先退休，只有所属进程确认退出后才释放清理责任；失败可由后续关闭重试。
+        # 打开前也使用同一路径，但保留调用方为新连接设置的日志目标。
+        def close_resources
+          failure = nil
+          Thread.handle_interrupt(Exception => :never) do
+            @closing_channel = @channel if @channel
+            @channel = nil
+            status = @closing_channel&.hard_close
+            # fork 副本只关闭继承句柄；父进程拥有的子进程不能成为本副本的回收前提。
+            if @channel_owner == Process.pid && @closing_channel&.alive?
+              raise IOError, "PTY child is still running after hard close"
+            end
+
+            @closing_channel = nil
+            @channel_owner = nil
+            status
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 延迟取消不能覆盖底层关闭的首个故障。
+            failure = error
+            raise
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 先保存完成边界，再交付最先观察到的故障。
+          raise failure || error, cause: nil
+        end
+
         # 已有操作异常时仍尝试清理；次级故障或中断不能覆盖原始失败。
         def close_preserving_failure
           close
@@ -154,6 +170,7 @@ module Net
         def open
           failure = nil
           configuration.validate_endpoint!
+          close_resources if @channel || @closing_channel || @known_hosts
           unless configuration.host_key_policy == :strict
             # 临时信任文件的返回交接与信道遵守同一所有权边界。
             Thread.handle_interrupt(Exception => :on_blocking) do
@@ -175,33 +192,6 @@ module Net
           @replace_host_key = false
         end
 
-        # 同时回收 SSH 通道与私有信任快照，保留先发生的关闭故障。
-        def close
-          failure = nil
-          # 一次取消须等待信道和信任快照均完成回收；同步故障仍保留首个。
-          Thread.handle_interrupt(Exception => :never) do
-            known_hosts = @known_hosts
-            @known_hosts = nil
-            begin
-              super
-            rescue Exception => error # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
-              failure = error
-              raise
-            ensure
-              begin
-                known_hosts&.close
-              rescue Exception => error # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
-                unless failure
-                  failure = error
-                  raise
-                end
-              end
-            end
-          end
-        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付也不能盖掉已经发生的关闭故障。
-          raise failure || error, cause: nil
-        end
-
         # 返回 SSH 协议标识。
         def protocol = :ssh
 
@@ -236,6 +226,35 @@ module Net
           @replace_host_key = true
         end
 
+        private
+
+        # 同时回收 SSH 通道与私有信任快照，保留先发生的关闭故障。
+        def close_resources
+          failure = nil
+          # 一次取消须等待信道和信任快照均完成回收；同步故障仍保留首个。
+          Thread.handle_interrupt(Exception => :never) do
+            known_hosts = @known_hosts
+            @known_hosts = nil
+            begin
+              super
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
+              failure = error
+              raise
+            ensure
+              begin
+                known_hosts&.close
+              rescue Exception => error # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
+                unless failure
+                  failure = error
+                  raise
+                end
+              end
+            end
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付也不能盖掉已经发生的关闭故障。
+          raise failure || error, cause: nil
+        end
+
       end
 
       # Telnet 只能显式启用；SSH 专用端口不能带入回退连接。

data/lib/net/connector/inventory/filters.rb

@@ -33,7 +33,7 @@ module Net
         def self.add_options(parser, single_host: true, &accept)
           flags = single_host ? {"--host IP" => "hosts"}.merge(FLAGS) : FLAGS
           flags.each do |flag, key|
-            parser.on(flag, "筛选已有清单，同类条件取并集，排除优先") do |value|
+            parser.on(flag, "Filter inventory; combine conditions of the same type with OR; exclusions take precedence") do |value|
               items = value.split(",", -1).map(&:strip)
               raise OptionParser::InvalidArgument, "filter list contains empty items" if items.empty? || items.any?(&:empty?)
 
@@ -41,7 +41,7 @@ module Net
             end
           end
           MODES.each do |key|
-            parser.on("--#{key.tr("_", "-")} MODE", %w[contains prefix glob], "匹配方式 contains / prefix / glob") { |value| accept.call(key, value) }
+            parser.on("--#{key.tr("_", "-")} MODE", %w[contains prefix glob], "Matching mode: contains / prefix / glob") { |value| accept.call(key, value) }
           end
         end
       end

data/lib/net/connector/netdisco/cli/backup.rb

@@ -58,13 +58,13 @@ module Net
             finish_interrupted(fleet, progress, options, batch_directory, plan, settings)
             130
           rescue EOFError
-            @error.puts "配置输入未完成，已停止；请检查先前提示的文件。"
+            @error.puts "Configuration setup is incomplete; stopped. Check the files listed above."
             2
           rescue ArgumentError, Inventory::Error => exception
-            @error.puts "备份参数或清单错误：#{exception.message}"
+            @error.puts "Backup argument or inventory error: #{exception.message}"
             2
           rescue StandardError => exception
-            @error.puts "备份未完成（#{exception.class}）"
+            @error.puts "Backup incomplete (#{exception.class})"
             2
           end
 
@@ -111,10 +111,10 @@ module Net
           # 清单离线回退和本地保存故障单独提示，不覆盖设备操作结果。
           def inventory_warning(fleet)
             if fleet.inventory_status && fleet.inventory_status[:source] == :stale_cache
-              @error.puts "清单刷新失败，使用历史缓存（#{fleet.inventory_status[:refresh_error_code]}）"
+              @error.puts "Inventory refresh failed; using the previous cache (#{fleet.inventory_status[:refresh_error_code]})"
             end
             return unless fleet.inventory_status && fleet.inventory_status[:write_error_type]
-            @error.puts "清单缓存写入失败（#{fleet.inventory_status[:write_error_type]}）"
+            @error.puts "Inventory cache write failed (#{fleet.inventory_status[:write_error_type]})"
 
           end
 
@@ -188,7 +188,7 @@ module Net
             progress.finish(report)
             progress.location(report.report_location) if report.report_location
             summary_path = File.join(batch_directory, "summary.txt")
-            progress.location(summary_path, label: "文本报告") if File.file?(summary_path)
+            progress.location(summary_path, label: "Text report") if File.file?(summary_path)
             updated = record_progress_error(report, progress)
             unless updated.equal?(report)
               # 末尾显示也可能首次失败，只补写诊断，不重复设备任务或事件。

data/lib/net/connector/netdisco/cli/credentials.rb

@@ -18,10 +18,10 @@ module Net
             begin
               values = JSON.parse(input.gets("\n") || "")
             rescue JSON::ParserError
-              raise ArgumentError, "凭据 JSON 无效", cause: nil
+              raise ArgumentError, "Invalid credentials JSON", cause: nil
             end
             keys = %w[netdisco_username netdisco_password device_username device_password]
-            raise ArgumentError, "需要四个非空凭据字符串" unless values.is_a?(Hash) && keys.all? { |key| values[key].is_a?(String) && !values[key].strip.empty? }
+            raise ArgumentError, "Four nonempty credential strings are required" unless values.is_a?(Hash) && keys.all? { |key| values[key].is_a?(String) && !values[key].strip.empty? }
 
             inventory = settings.inventory(credentials: {
               username: values.fetch("netdisco_username"), password: values.fetch("netdisco_password")