net-connector 0.9.0 → 0.10.1

data/lib/net/connector/device/topology/stages.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/command"
+require_relative "interface_description"
+
+module Net
+  module Connector
+    class Topology
+      # 离线预检与现场执行共用确切阶段，不复制厂商命令或把保存合并到变更阶段。
+      module Stages
+        def self.build(strategy:, host:, changes:)
+          validate_changes!(strategy, changes)
+          phases = %i[leave_configuration_commands verification_commands persistence_commands].map do |method|
+            strategy.public_send(method)
+          end
+          unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
+            raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
+                                           code: :description_stages_unsupported, host: host, phase: :plan)
+          end
+          leave, verify, persist = phases
+          commands = changes.flat_map do |change|
+            strategy.change_commands(change)
+          end
+          sequences = { change: [strategy.enter_configuration_command] + commands + leave,
+                        verify: verify, persist: persist }
+          sequences.transform_values do |sequence|
+            Script.new(sequence.map { |command| strategy.script_command(command) }, name: "interface descriptions")
+          end
+        end
+
+        # 同一物理接口只能出现一次；缩写与全称也不能绕过离线和现场的共同预检。
+        def self.validate_changes!(strategy, changes)
+          unless changes.is_a?(Array) && changes.all?(Topology::Change)
+            raise ArgumentError, "topology changes must be an Array of Changes"
+          end
+
+          interfaces = {}
+          changes.each do |change|
+            InterfaceDescription.validate_interface!(change.interface)
+            key = strategy.interface_key(change.interface)
+            raise ArgumentError, "topology changes must identify unique interfaces" if interfaces.key?(key)
+
+            interfaces[key] = true
+          end
+        end
+        private_class_method :validate_changes!
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "topology/strategy"
+require_relative "topology/stages"
 
 module Net
   module Connector
@@ -14,6 +15,11 @@ module Net
         # 读取运行配置中的接口描述或端口名称。
         def interface_descriptions = Topology.new(self).interface_descriptions
 
+        # 显式同步请求在同一会话中完成发现、修改、读回与保存，无须调用方传递计划。
+        def sync_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).sync_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
         # 以邻居和现有配置为证据，生成待确认的接口描述变更计划。
         def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
           Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
@@ -29,6 +35,50 @@ module Net
       Change = Data.define(:interface, :old_description, :new_description, :neighbor)
       Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
 
+      # 仅承载厂商档案的离线上下文，不能连接、查询或下发设备命令。
+      PlanningContext = Data.define(:host, :vendor, :profile) do
+        def config_commands = profile.config_commands
+      end
+      private_constant :PlanningContext
+
+      # 全批应用前拒绝可离线判定的能力或命令问题；现场证据仍由单设备操作重验。
+      def self.validate_plan!(plan, host:, vendor:)
+        unless plan.is_a?(Plan) && plan.host == host && plan.vendor == vendor
+          raise ArgumentError, "plan must match its target device"
+        end
+        if plan.changes.empty?
+          raise ArgumentError, "empty topology plan cannot contain commands" unless plan.commands.empty?
+
+          return plan
+        end
+        strategy = planning_strategy(host: host, vendor: vendor)
+        validate_change_support!(strategy, host: host, phase: :apply)
+        stages = Stages.build(strategy: strategy, host: host, changes: plan.changes)
+        unless stages.values.flat_map { |script| script.map(&:text) } == plan.commands
+          raise ArgumentError, "plan commands were modified or use an older execution sequence; regenerate the plan"
+        end
+        plan
+      end
+
+      # 批次规划在建立任一会话前检查整个目标集合的厂商写入能力。
+      def self.validate_vendor_support!(host:, vendor:, phase:)
+        validate_change_support!(planning_strategy(host: host, vendor: vendor), host: host, phase: phase)
+      end
+
+      def self.planning_strategy(host:, vendor:)
+        profile = Net::Connector.vendor_class(vendor).profile
+        (profile.topology_strategy || Strategy).new(PlanningContext.new(host: host, vendor: vendor, profile: profile))
+      end
+      private_class_method :planning_strategy
+
+      # 能力声明不需要会话；规划、批次预检和现场应用使用同一厂商规则。
+      def self.validate_change_support!(strategy, host:, phase:)
+        return if strategy.supports?(:interface_description_changes)
+
+        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
+                                       code: strategy.change_error_code, host: host, phase: phase)
+      end
+
       # 保存设备及其独立的 TextFSM 解析入口。
       def initialize(device, template_dir: nil)
         require_relative "../textfsm"
@@ -92,6 +142,18 @@ module Net
 
       private :read_interface_descriptions
 
+      # 调用即表达修改意图；同一租约覆盖发现到保存，外部变更仍须重验。
+      def sync_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+          raise ArgumentError, "description formatting options must be boolean"
+        end
+        validate_change_support!(:apply)
+        @device.with_operation(:apply) do
+          plan = plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+          plan.changes.empty? ? Result.new : apply_plan(plan)
+        end
+      end
+
       # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
       def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
@@ -210,21 +272,7 @@ module Net
 
       # 审批列表保留真正执行的读回命令，使旧版“先保存后读回”计划无法静默复用。
       def stage_scripts(changes)
-        phases = %i[leave_configuration_commands verification_commands persistence_commands].map do |method|
-          @strategy.public_send(method)
-        end
-        unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
-          raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
-                                         code: :description_stages_unsupported, host: @device.host, phase: :plan)
-        end
-        leave, verify, persist = phases
-        sequences = {
-          change: [@strategy.enter_configuration_command] + changes.flat_map { |change| change_commands(change) } + leave,
-          verify: verify, persist: persist
-        }
-        sequences.transform_values do |commands|
-          Script.new(commands.map { |command| @strategy.script_command(command) }, name: "interface descriptions")
-        end
+        Stages.build(strategy: @strategy, host: @device.host, changes: changes)
       end
 
       def execute_stage(script, steps)
@@ -242,10 +290,7 @@ module Net
 
       # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
       def validate_change_support!(phase)
-        return if @strategy.supports?(:interface_description_changes)
-
-        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
-                                       code: @strategy.change_error_code, host: @device.host, phase: phase)
+        self.class.validate_change_support!(@strategy, host: @device.host, phase: phase)
       end
 
       # 汇总邻居身份和当前描述，并要求每个目标接口都有配置证据。
@@ -267,11 +312,7 @@ module Net
         end.freeze
       end
 
-      # 设备标识来自解析证据，仍需在生成命令前验证其安全性。
-      def change_commands(change)
-        InterfaceDescription.validate_interface!(change.interface)
-        @strategy.change_commands(change)
-      end
+
     end
   end
 end

data/lib/net/connector/device_session.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 一个设备任务独占一个连接器；返回值与收尾故障分别保留，不能靠重试恢复写操作。
+    module DeviceSession
+      # 工厂负责构造，作用域负责关闭；中断仍向调用方传播且不会被第二个关闭故障覆盖。
+      def self.call(factory:)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+        raise ArgumentError, "device session requires a block" unless block_given?
+
+        connector = value = failure = nil
+        completed = false
+        begin
+          # 构造器在阻塞等待中仍可取消；非阻塞的返回交接须先登记所有权再交付取消。
+          # 工厂尚未返回时的部分资源由工厂清理，成功返回后统一由本作用域关闭。
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            connector = factory.call
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 工厂同步故障先于退出屏蔽范围时交付的取消。
+            failure = error
+            raise
+          end
+          value = yield connector
+          completed = true
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 收尾后保留最先发生的中断，普通故障单独交付业务层。
+          failure ||= error
+          completed = true
+        ensure
+          begin
+            # 二次异步取消须等待关闭完成，不能在收尾中再次丢失资源所有权。
+            Thread.handle_interrupt(Exception => :never) { connector&.close }
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 关闭故障不能覆盖原操作故障，包括 Interrupt。
+            failure ||= error
+          end
+          # break 和非局部 return 跳过尾部返回值；收尾故障必须在展开作用域时交付。
+          raise failure if failure && (!completed || !failure.is_a?(StandardError))
+        end
+
+        [value, failure]
+      end
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ module Net
         @host = "[#{@host}]:#{configuration.port}" if configuration.port && configuration.port != 22
         @replace = replace
         @original = read_shared
-        @file = Tempfile.new([".nc-known-hosts-", ""], File.dirname(@destination))
+        create_snapshot
         @path = @file.path
         @file.write(@original)
         @file.flush
@@ -57,6 +57,36 @@ module Net
       end
 
       def close
+        failure = nil
+        # 清除引用至删除快照期间延后异步取消，不能留下失去所有者的临时文件。
+        Thread.handle_interrupt(Exception => :never) do
+          close_snapshot
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 保存同步清理故障，退出屏蔽范围后继续传播。
+          failure = error
+          raise
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 延迟取消不能覆盖清理过程中已经发生的故障。
+        raise failure || error, cause: nil
+      end
+
+      private
+
+      # 临时文件返回后先登记所有权，阻塞构造期间仍允许取消。
+      def create_snapshot
+        failure = nil
+        begin
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            @file = Tempfile.new([".nc-known-hosts-", ""], File.dirname(@destination))
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 构造故障先于退出屏蔽范围时递送的二次取消。
+            failure = error
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 成功交接后取消仍传播，但不覆盖已登记的构造故障。
+          failure ||= error
+        end
+        raise failure, cause: nil if failure
+      end
+
+      def close_snapshot
         file = @file
         @file = nil
         File.unlink(@path + ".old") if @path && File.exist?(@path + ".old")
@@ -71,8 +101,6 @@ module Net
         end
       end
 
-      private
-
       # 初始化失败时保留原始异常，同时尽力清理已经创建的临时文件。
       def close_preserving_failure
         close

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

@@ -31,15 +31,17 @@ module Net
         @transport = transport
         @session_id = SecureRandom.hex(8).freeze
         @command_sequence = 0
-        @io = open_file(@configuration.log_file) if @configuration.log_file
+        open_file(@configuration.log_file) if @configuration.log_file
         if @configuration.log_format == :raw
           @writer = @output = RedactingWriter.new(@io, @redactor) if @io
         elsif @io || @configuration.logger
           @logger = @configuration.logger || ::Logger.new(@io, formatter: Formatter.new)
           open_transcript if @io && @configuration.log_level == :debug
         end
-      rescue => error
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 文件已登记后的中断也必须释放资源，仍原样交付中断。
         close_preserving_failure
+        raise unless error.is_a?(StandardError)
+
         raise build_error("unable to open session log", error), cause: nil
       end
 
@@ -192,10 +194,16 @@ module Net
           failed = true
           raise
         ensure
+          close_failure = nil
           begin
-            @io&.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
-            raise unless failed
+            Thread.handle_interrupt(Exception => :never) do
+              @io&.close
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 文件关闭先发生的故障优先于待处理中断。
+              close_failure = error
+              raise
+            end
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 文件关闭不能覆盖首个日志收尾故障或中断。
+            raise close_failure || error, cause: nil unless failed
           ensure
             @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
@@ -244,29 +252,28 @@ module Net
 
       # 以私有权限打开设备日志文件。
       def open_file(path)
+        failure = nil
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
-        begin
-          # FIFO 的打开不受登录截止时间约束；验证同一个 FD 后才能修改权限或写入。
-          raise ArgumentError, "session log must be a regular file" unless file.stat.file?
-
-          file.chmod(0o600)
-          file.binmode
-          file.write("\n") if file.size.positive? && @configuration.log_format == :text
-          file
-        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也释放尚未完成设置的文件。
-          begin
-            file.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 保留文件设置的原始故障或中断。
-            # 保留设置失败的原始原因。
-          end
+        # 返回文件后先登记唯一所有者；后续设置失败由 open 统一释放，不重复交接资源。
+        Thread.handle_interrupt(Exception => :never) do
+          @io = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 非阻塞打开的主故障不能被待处理中断替换。
+          failure = error
           raise
         end
+        # FIFO 的打开不受登录截止时间约束；验证同一个 FD 后才能修改权限或写入。
+        raise ArgumentError, "session log must be a regular file" unless @io.stat.file?
+
+        @io.chmod(0o600)
+        @io.binmode
+        @io.write("\n") if @io.size.positive? && @configuration.log_format == :text
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复取消交付时仍保留打开阶段的首个故障。
+        raise failure || error, cause: nil
       end
 
       # 在日志打开失败后尽力释放资源。
       def close_preserving_failure
-        close
+        Thread.handle_interrupt(Exception => :never) { close }
       rescue Exception # rubocop:disable Lint/RescueException -- 清理故障或中断不能覆盖日志打开失败。
         nil
       end

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

@@ -37,18 +37,23 @@ module Net
 
         # 打开伪终端、设置终端大小并启动设备进程。
         def open
+          failure = nil
           configuration.validate_endpoint!
-          @channel = if @channel_factory
-                       @channel_factory.call
-                     else
-                       if defined?(Expect::Session)
+          # 构造期间的阻塞仍可取消；返回交接先登记信道，再交付异步中断。
+          Thread.handle_interrupt(Exception => :on_blocking) do
+            @channel = if @channel_factory
+                         @channel_factory.call
+                       elsif defined?(Expect::Session)
                          Expect::Session.new(buffer_limit: nil, write_timeout: configuration.write_timeout)
                        else
                          Expect.new(raw_pty: true, reset_timeout_on_read: false, buffer_limit: nil,
-                                  preserve_buffer: false, log_stdout: false, log_listeners: false,
-                                  debug_level: 0, write_timeout: configuration.write_timeout)
+                                    preserve_buffer: false, log_stdout: false, log_listeners: false,
+                                    debug_level: 0, write_timeout: configuration.write_timeout)
                        end
-                     end
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 退出屏蔽范围交付取消之前，先保存构造器的同步故障。
+            failure = error
+            raise
+          end
           # Profile 使用宽、高；PTY 使用行数、列数。
           @channel.slave.winsize = @terminal_size.reverse if @terminal_size
           if @channel.respond_to?(:transcript=)
@@ -65,9 +70,9 @@ module Net
             @channel.spawn(*argv)
           end
           self
-        rescue Exception # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 中断时也必须释放尚未完成初始化的 PTY。
           close_preserving_failure
-          raise
+          raise failure || error, cause: nil
         end
 
         # 从信道读取下一事件，并把字符串字段转换为字节字符串。
@@ -80,11 +85,21 @@ module Net
 
         # 临时设置写入超时，完成写入后恢复原设置。
         def write(bytes, timeout: configuration.write_timeout)
-          previous = @channel.write_timeout
-          @channel.write_timeout = timeout
-          @channel.write(bytes)
-        ensure
-          @channel.write_timeout = previous if @channel
+          channel = @channel
+          previous = channel.write_timeout
+          begin
+            channel.write_timeout = timeout
+            channel.write(bytes)
+          rescue Exception # rubocop:disable Lint/RescueException -- 恢复超时前保留写入的首个故障或中断。
+            failed = true
+            raise
+          ensure
+            begin
+              channel.write_timeout = previous
+            rescue Exception # rubocop:disable Lint/RescueException -- 收尾故障不能把中断转换成普通写入错误。
+              raise unless failed
+            end
+          end
         end
 
         # 判断信道尚未建立或已经关闭。
@@ -97,10 +112,19 @@ module Net
 
         # 清除信道和日志目标，并强制关闭底层进程。
         def close
-          channel = @channel
-          @channel = nil
-          @log_target = nil
-          channel&.hard_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
         end
 
         # 把人工交互结果转换为设备 EOF、超时或输入状态。
@@ -146,14 +170,21 @@ module Net
         end
 
         def open
+          failure = nil
           configuration.validate_endpoint!
           unless configuration.host_key_policy == :strict
-            @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+            # 临时信任文件的返回交接与信道遵守同一所有权边界。
+            Thread.handle_interrupt(Exception => :on_blocking) do
+              @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 构造器先失败时，延迟取消不得覆盖其原始异常。
+              failure = error
+              raise
+            end
           end
           super
-        rescue Exception # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 启动失败或中断时释放临时信任文件。
           close_preserving_failure
-          raise
+          raise failure || error, cause: nil
         end
 
         def authenticated
@@ -162,18 +193,29 @@ module Net
         end
 
         def close
-          known_hosts = @known_hosts
-          @known_hosts = nil
-          super
-        rescue Exception # rubocop:disable Lint/RescueException -- 全部资源均须尝试关闭，保留首个失败或中断。
-          failed = true
-          raise
-        ensure
-          begin
-            known_hosts&.close
-          rescue Exception # rubocop:disable Lint/RescueException -- 信任文件收尾不能覆盖传输关闭的原始异常。
-            raise unless failed
+          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 协议标识。

data/lib/net/connector/execution_pool.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 仅管理有限并发和线程所有权；业务层负责将普通任务故障转换为领域结果。
+    class ExecutionPool
+      DEFAULT_CONCURRENCY = 4
+      MAX_CONCURRENCY = 50
+
+      def self.validate_concurrency!(concurrency)
+        unless concurrency.is_a?(Integer) && (1..MAX_CONCURRENCY).cover?(concurrency)
+          raise ArgumentError, "concurrency must be an Integer in 1..#{MAX_CONCURRENCY}"
+        end
+
+        concurrency
+      end
+
+      # 环境只提供默认并发数；显式构造参数优先，非法值不创建线程。
+      def self.environment_concurrency(env: ENV)
+        value = env.fetch("NC_CONCURRENCY", DEFAULT_CONCURRENCY.to_s)
+        unless value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+          raise ArgumentError, "NC_CONCURRENCY must be a positive integer"
+        end
+
+        validate_concurrency!(Integer(value, 10))
+      end
+
+      def initialize(concurrency: self.class.environment_concurrency)
+        @concurrency = self.class.validate_concurrency!(concurrency)
+      end
+
+      # 保序返回块的值；任何未处理异常均在调用线程抛出，停止并回收本次所有线程。
+      # 只复制任务数组，任务内容仍由业务层在下发前校验和固定，不自动重放块。
+      def map(items)
+        raise ArgumentError, "items must be an Array" unless items.is_a?(Array)
+        raise ArgumentError, "map requires a block" unless block_given?
+
+        items = items.dup
+        queue = Queue.new
+        items.each_with_index { |item, index| queue << [index, item] }
+        count = [items.size, @concurrency].min
+        count.times { queue << nil }
+        gate = Queue.new
+        finished = Queue.new
+        results = Array.new(items.size)
+        threads = []
+        completed = false
+        primary_failure = nil
+        begin
+          count.times do
+            # 仅延迟线程创建到登记的异步中断，避免尚未登记的工作线程失去所有者。
+            Thread.handle_interrupt(Exception => :never) do
+              threads << Thread.new do
+                failure = nil
+                begin
+                  # 全部线程成功建立后才允许设备操作，创建失败不能留下已发送的变更。
+                  Thread.handle_interrupt(Exception => :immediate) do
+                    gate.pop
+                    while (task = queue.pop)
+                      index, item = task
+                      results[index] = yield item
+                    end
+                  end
+                rescue Exception => error # rubocop:disable Lint/RescueException -- 将中断同步交给调用线程，避免全局 abort_on_exception 波及其他线程。
+                  failure = error
+                ensure
+                  finished << [Thread.current, failure]
+                end
+              end
+            end
+          end
+          count.times { gate << true }
+          count.times do
+            thread, failure = finished.pop
+            thread.join
+            raise failure if failure
+          end
+          completed = true
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 记录取消或原任务故障，收尾中再次取消不能覆盖它。
+          primary_failure = error
+          raise
+        ensure
+          stop_threads(threads, primary_failure) unless completed
+        end
+        results
+      end
+
+      private
+
+      # kill 运行任务自身的 ensure；次级关闭故障不能盖掉已观察到的原始异常。
+      def stop_threads(threads, primary_failure)
+        # 仅回收期间延迟异步取消；交付二次中断之前必须 kill 并 join 全部拥有线程。
+        Thread.handle_interrupt(Exception => :never) do
+          threads.each(&:kill)
+          threads.each do |thread|
+            begin
+              thread.join
+            rescue Exception # rubocop:disable Lint/RescueException -- 等待全部拥有线程收尾，保留调用方原始故障或中断。
+              nil
+            end
+          end
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复交付时保留原故障，二次取消不改变批次失败原因。
+        # 二次取消可能已以原故障为 cause；不能反向关联形成异常原因环。
+        raise primary_failure || error, cause: nil
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/backup_run.rb

@@ -33,11 +33,13 @@ module Net
           fleet = Fleet.new(client: client, settings: settings, credentials: resolver, result_store: nil)
           progress.reading_inventory
           limit = settings.limit_per_vendor
+          refresh = options[:force_refresh] ? { force_refresh: true } : {}
           plan = if @mode == :backup
-                   fleet.plan_backup(limit_per_vendor: limit)
+                   fleet.plan_backup(limit_per_vendor: limit, **refresh)
                  else
-                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?)
+                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?, **refresh)
                  end
+          inventory_warning(fleet)
           progress.plan(plan, concurrency: settings.concurrency, limit_per_vendor: limit)
           preview = plan_summary(plan)
           @output.puts JSON.generate(plan: preview) if options[:json]
@@ -59,6 +61,16 @@ module Net
 
         private
 
+        # 清单离线回退和本地保存故障单独提示，不覆盖设备操作结果。
+        def inventory_warning(fleet)
+          if fleet.inventory_status && fleet.inventory_status[:source] == :stale_cache
+            @error.puts "清单刷新失败，使用历史缓存（#{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]}）"
+
+        end
+
         # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
         def prepare(options)
           settings = CLI::Options.settings(options, env: @env).for_run(mode: @mode)