net-connector 0.17.2 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aadffbf2db023105e9b507fb732a89bd710207adf28456b2edb5184eb245fedf
-  data.tar.gz: 72cc71886fd9c6dce77171af3c8300f5f84af7c7e8192acd335e132c942b2b3c
+  metadata.gz: 87b108e7525f64a9df67db08537eafa2e3c2845797fccea6fe09fdb5701696fd
+  data.tar.gz: f6c6bea9be822222feb3056e2866b39d35209b4fe06b108613c059261b987467
 SHA512:
-  metadata.gz: 4d59d23ae05999d469f96837baf6b5f2eca3518104b8769947c36c860788627f3f9cb35c4e05151e364e51f159f0b171905f64fbfd30b963d096bf176cbf35d5
-  data.tar.gz: 0b0137d959ecc3be69fd72fbed2bcc562e95c615ab13a786c4485dcf107ff9de30376e2c731051edbac6f297b496be1cdc97c2ec321066c955c9a3a88ef369f6
+  metadata.gz: de0022df96e76aeeec4bd916c7abd27f9fb4646269d552846d07d1c575a05593fbf3605a25f271574a48202e81100986fb5508e44c162c6b1668c158bcad9ae9
+  data.tar.gz: 749ba87f2702d94098e02b3cf7f9fae6e00557f219c796e453028b7d67db07f1c7469985ad8275818de71b50a1bfc7b2319936e502817f7057f5b3a59c670cd7

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.18.1 - 2026-10-24
+
+- Stream SSH archive bodies through bounded binary frames and incremental hashes instead of whole-file base64 copies; preserve deadlines, verified server receipts and committed local paths.
+- Retain cleanup ownership across cancellation, failed closes and forked KnownHosts snapshots; reject inherited trust commits before file or lock access.
+- Preserve the primary exception or nonlocal exit when atomic-file and archive-process cleanup also fails.
+- Expose JSON Pointer field provenance through configuration previews and leave runtime dependency versions to host lockfiles.
+
+## 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.

data/docs/architecture.md

@@ -88,12 +88,20 @@ Fleet 在规范目标校验、凭据解析及连接器构造之前加同一把
 
 `KnownHosts` 在跨进程锁内重读和合并已认证的会话密钥，条目索引保留原顺序及已有重复行，新增行只登记一次。提交复用 `AtomicFile`；目录同步失败保留已替换文件并报告 `file_persistence_unconfirmed`，不能触发再次登记。不安全的非普通共享信任文件报告 `known_hosts_unsafe`，strict 模式仍由 OpenSSH 管理。写入器仅在实际提交时加载，纯会话引擎加载不引入存储层。
 
+信任快照及其 `.old` 文件由创建进程拥有。fork 副本关闭时只释放继承描述符；提交继承快照（即使没有新增密钥）在读取和加锁前报告 `known_hosts_inherited`。子进程需要重新打开 SSH 连接，取得自己的快照后再认证和登记；父进程的快照与连接继续有效。快照关闭失败时，KnownHosts 和 Ssh 保留清理责任，后续 close/open 重试，清理成功后才释放引用。
+
 提交后的 `BackupPersistenceError` 只携带原 `Backup` 元数据和受控写入回执，Fleet 保留产物并使用已有 saved_with_error 分类。只接受库定义的具体完成错误及匹配产物类型，第三方异常的 backup 属性或自定义 WriteError 子类不作为完成证据。报告保留已提交位置，导出错误说明 committed；设备命令不会自动重放。
 
 直接备份在路径锁退出前保存完成元数据，锁关闭的普通故障转换为 `BackupFinalizeError`，其中 `backup` 保留结果，`underlying_type` 经过类型白名单。该错误只确认备份操作已完成，不制造文件同步回执；未变文件的历史持久性仍未补验。Fleet 的外层路径锁及 TFTP 归档锁同样保存最新结果，退出故障转为 saved_with_error 或 reported_with_error，已有设备诊断优先，中断继续传播。
 
 TFTP 归档分别保留本地批次副本与服务器归档副本的提交位置；写入器的原生回执必须与本次目标路径一致。目录同步或收尾失败仍保留已提交路径，成功上传转为 `reported_with_error`，诊断记录归档失败及持久化阶段；设备任务此前已有错误时保留原诊断。报告失败后的 JSON 补写同样保留已提交位置，不覆盖首次报告故障，也不重新执行设备任务。
 
+SSH 归档的 Client 持有事务进程和管道，Protocol 只借用 IO，维护 16 KiB 控制帧、64 KiB 正文片段和阶段截止时间。`archived` 元数据、声明长度的二进制正文与 `delivered` 确认共用 280 秒期限；文件上限仍为 64 MiB，并发槽位仍为 4。Python 工作进程分片读取、复制和摘要核验，复制及交付前后均检查文件身份、大小与目录/锁边界，不保留整份正文或 base64 副本。
+
+`AtomicFile.write_stream` 借出私有临时文件，只有正文长度、SHA-256 和交付确认全部通过后，才允许同步和原子替换。本地准备或写盘失败时，Client 尽可能继续有界读取并核验服务器副本，保留 `server_verified`，随后发送 abort，保持 staging；失败写入和设备上传均不重试。原子替换之后的同步故障保留可信回执中的 `local_path`。启动器只返回管道与等待线程，Client 是唯一清理者，取消和非局部退出不会被普通关闭错误覆盖。
+
+AtomicFile 同样独占临时文件及父目录句柄的清理。取得句柄和登记临时目录项身份共用取消保护边界；清理仍尝试关闭及移除属于本次写入的临时目录项。生产者或目录同步期间的异常、取消及非局部退出优先于普通关闭错误；正常完成后的清理错误继续按原写入回执报告。
+
 TFTP 只确认设备报告的上传结果：策略去掉命令、应答和提示符回显后，检查明确的完成行；文件名或表示“即将上传”的进度文字不算成功。原始输出或终端渲染文本中的失败证据优先于成功文字。
 
 失败证据核对与完成核对共用精确回显过滤。静态应答从已完成步骤的 `Command#interactions` 读取，`Interaction#static_response` 对动态回调返回 nil，核对不会重新执行挑战回调。失败核对逐步读取原文、回车历史和终端画面，不累积全部画面副本；颜色样式只影响显示，不能拆开诊断词或借光标擦除隐藏已经收到的失败。命令诊断及拓扑保存确认同样保留这类失败历史。
@@ -206,8 +214,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/error/metadata.rb

@@ -25,7 +25,8 @@ module Net
              Net::Connector::Netdisco::Tftp::Archive::Unavailable Net::Connector::Netdisco::Tftp::Archive::Failure]).freeze
         CODES = (CONNECTOR_TYPES.map { |name| name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym } +
           %i[authentication_failed connection_failed connection_refused no_route connection_reset
-             connection_timeout host_key_changed host_key_untrusted known_hosts_busy known_hosts_unsafe rsa_too_small unsupported_cipher
+             connection_timeout host_key_changed host_key_untrusted known_hosts_busy known_hosts_unsafe known_hosts_inherited
+             rsa_too_small unsupported_cipher
              ambiguous_description ambiguous_neighbor confirmation_required description_stages_unsupported
              description_unconfirmed description_unsupported incomplete_configuration interface_missing
              neighbor_discovery_unsupported parse_failed invalid_output_encoding persistence_unconfirmed stale_plan startup_config_missing

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

@@ -14,6 +14,7 @@ module Net
 
       # 建立本次连接的私有主机密钥快照，初始化失败时清理已取得的资源。
       def initialize(configuration, replace: false)
+        @owner_pid = Process.pid
         destination = configuration.known_hosts || File.join(Dir.home, ".ssh", "known_hosts")
         FileUtils.mkdir_p(File.dirname(destination), mode: 0o700)
         @destination = File.join(File.realpath(File.dirname(destination)), File.basename(destination))
@@ -35,6 +36,11 @@ module Net
       # 在目标文件锁内合并新增信任；检测并发密钥变化后原子写回。
       # 会话只写私有快照；登记时重读共享信任并检查冲突，避免并发连接覆盖已有主机密钥。
       def commit
+        unless @owner_pid == Process.pid
+          raise ConnectionError.new("inherited known_hosts snapshot cannot be committed; reopen the SSH connection",
+                                    code: :known_hosts_inherited, host: @host, phase: :login), cause: nil
+        end
+
         # 纯会话引擎加载不触及文件业务；实际登记信任时才加载持久化协议。
         require_relative "../storage/atomic_file"
         begin
@@ -60,10 +66,10 @@ module Net
         end
       end
 
-      # 关闭并删除私有密钥快照，延迟取消直至清理完成。
+      # 关闭私有密钥快照，创建进程同时删除文件；延迟取消直至清理完成。
       def close
         failure = nil
-        # 清除引用至删除快照期间延后异步取消，不能留下失去所有者的临时文件。
+        # 关闭句柄和删除快照期间延后异步取消，完成清理后再释放引用。
         Thread.handle_interrupt(Exception => :never) do
           close_snapshot
         rescue Exception => error # rubocop:disable Lint/RescueException -- 保存同步清理故障，退出屏蔽范围后继续传播。
@@ -104,17 +110,24 @@ module Net
         raise failure, cause: nil if failure
       end
 
-      # 清除快照引用并删除临时文件，清理错误不覆盖较早的失败。
+      # 创建进程负责删除文件；fork 副本只关闭继承句柄，失败时保留清理引用。
       def close_snapshot
         file = @file
-        @file = nil
-        File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
+        owned = @owner_pid == Process.pid
+        File.unlink(@path + ".old") if owned && @path && File.exist?(@path + ".old")
       rescue Exception # rubocop:disable Lint/RescueException -- 删除附属文件失败或中断后仍须关闭私有快照。
         failed = true
         raise
       ensure
         begin
-          file&.close!
+          if owned
+            file&.close!
+            # Tempfile 会吞掉删除时的权限错误；路径仍存在表示删除责任尚未完成。
+            raise IOError, "known_hosts snapshot removal is incomplete" if file&.path
+          else
+            file&.close
+          end
+          @file = nil
         rescue Exception # rubocop:disable Lint/RescueException -- 私有快照清理不能覆盖先发生的删除故障。
           raise unless failed
         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
+            begin
+              super
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
+              failure = error
+              raise
+            ensure
+              begin
+                known_hosts&.close
+                @known_hosts = nil
+              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