diff --git a/ShadowsocksX-NG2/App/LegacyAppController.swift b/ShadowsocksX-NG2/App/LegacyAppController.swift
new file mode 100644
index 00000000..4bb39565
--- /dev/null
+++ b/ShadowsocksX-NG2/App/LegacyAppController.swift
@@ -0,0 +1,47 @@
+import AppKit
+
+/// NSWorkspace 实现的 Legacy app 检测缝（issue #37）：NG2 与 Legacy 共享
+/// bundle id（D1 继承），「正在运行的旧版 app」= 该 bundle id 下除自身进程外
+/// 的任何进程。NSRunningApplication 要求主线程，非主线程调用同步派发——
+/// 调用方（交接检测在后台任务）挂起等待而非阻塞主线程，无死锁。
+final class WorkspaceLegacyAppController: LegacyAppControlling {
+  static let legacyBundleIdentifier = "com.qiuyuzhou.ShadowsocksX-NG"
+
+  func isRunning() -> Bool {
+    MainActor.runUnsafelyIfNeeded { legacyApplication() != nil }
+  }
+
+  func isInstalled() -> Bool {
+    Self.bundleURLs.contains { FileManager.default.fileExists(atPath: $0.path) }
+  }
+
+  func requestGracefulQuit() -> Bool {
+    MainActor.runUnsafelyIfNeeded { legacyApplication()?.terminate() ?? false }
+  }
+
+  /// 常见安装位置（Legacy LaunchHelper 自身也按这些位置找主 app）。
+  private static let bundleURLs: [URL] = [
+    URL(fileURLWithPath: "/Applications/ShadowsocksX-NG.app"),
+    FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(
+      "Applications/ShadowsocksX-NG.app", isDirectory: true),
+  ]
+
+  private func legacyApplication() -> NSRunningApplication? {
+    NSRunningApplication
+      .runningApplications(withBundleIdentifier: Self.legacyBundleIdentifier)
+      .first { $0.processIdentifier != ProcessInfo.processInfo.processIdentifier }
+  }
+}
+
+extension MainActor {
+  /// 供非主线程上下文同步执行 AppKit 调用的小帮手；主线程上直接执行。
+  fileprivate static func runUnsafelyIfNeeded<T>(_ body: @MainActor () -> T) -> T {
+    if Thread.isMainThread {
+      // 主线程上已满足隔离要求，直接执行（MainActor.assumeIsolated）。
+      return MainActor.assumeIsolated(body)
+    }
+    return DispatchQueue.main.sync {
+      MainActor.assumeIsolated(body)
+    }
+  }
+}
diff --git a/ShadowsocksX-NG2/App/LegacyHandoffSheet.swift b/ShadowsocksX-NG2/App/LegacyHandoffSheet.swift
new file mode 100644
index 00000000..a7dc3ecf
--- /dev/null
+++ b/ShadowsocksX-NG2/App/LegacyHandoffSheet.swift
@@ -0,0 +1,291 @@
+import ServiceManagement
+import SwiftUI
+
+/// Legacy 交接确认与呈现面（issue #37，用户故事 7-9）：显式确认「切换到
+/// 2.0」后才停用旧版后台服务；告知系统代理将被清理（需授权）且非 Legacy 代
+/// 理不动；提示退出旧版 app（其 GUI 进程持有 PAC 端口）；Legacy 数据全部保
+/// 留，残留与旧登录项给人工处理指引。
+struct LegacyHandoffSheet: View {
+  @ObservedObject var viewModel: LegacyHandoffViewModel
+  @Environment(\.dismiss) private var dismiss
+
+  var body: some View {
+    VStack(alignment: .leading, spacing: 16) {
+      Text(title)
+        .font(.title2.weight(.semibold))
+      Text(
+        "此操作会：停用旧版的三个后台服务（ss-local、Privoxy、kcptun，仅限这几个名字）；清理旧版写入的系统代理（需要授权，其他软件的代理配置不会被改动）。旧版的配置、日志、二进制等数据全部保留，可随时回退。"
+      )
+      .font(.callout)
+      .foregroundStyle(.secondary)
+
+      switch viewModel.phase {
+      case .idle:
+        ProgressView().controlSize(.small)
+      case .ready:
+        detectionView
+      case .performing:
+        performingView
+      case .completed:
+        completedView
+      case .failed(let reason):
+        failedView(reason)
+      }
+
+      Spacer()
+      footerButtons
+    }
+    .padding(24)
+    .frame(width: 560, height: 620)
+    .task {
+      await viewModel.refresh()
+    }
+  }
+
+  private var title: String {
+    if case .completed = viewModel.phase { return "交接完成" }
+    return viewModel.handoffCompleted ? "Legacy 交接状态" : "切换到 2.0"
+  }
+
+  // MARK: - 识别结果（确认前）
+
+  @ViewBuilder
+  private var detectionView: some View {
+    ScrollView {
+      VStack(alignment: .leading, spacing: 12) {
+        if let detection = viewModel.detection {
+          if detection.legacyAppRunning {
+            legacyAppRunningCard
+          }
+          if !detection.printFailures.isEmpty {
+            Label(
+              "无法确认部分旧版服务状态：\(detection.printFailures.joined(separator: "、"))",
+              systemImage: "exclamationmark.triangle.fill"
+            )
+            .foregroundStyle(.orange)
+          }
+
+          stateSection(title: "旧版后台服务（launchd）") {
+            ForEach(LegacyLaunchAgentLabel.allCases, id: \.rawValue) { label in
+              let loaded = detection.loadedLabels.contains(label.rawValue)
+              HStack {
+                Image(systemName: loaded ? "circle.fill" : "circle")
+                  .foregroundStyle(loaded ? Color.orange : Color.secondary)
+                  .font(.system(size: 8))
+                Text(loaded ? "运行中：" + label.rawValue : "未加载：" + label.rawValue)
+                  .font(.callout)
+              }
+            }
+          }
+
+          let residues = detection.plists.filter { $0.fileExists }
+          if !residues.isEmpty {
+            stateSection(title: "残留的旧版 LaunchAgent 配置（保留，不自动删除）") {
+              ForEach(residues, id: \.label) { residue in
+                Text(residueDescription(residue))
+                  .font(.callout)
+                  .foregroundStyle(
+                    residue.isActiveForm ? AnyShapeStyle(.orange) : AnyShapeStyle(.secondary))
+              }
+            }
+          }
+
+          stateSection(title: "端口释放检查（交接完成前确认 1086/1087/1089 或自定义值）") {
+            Text("旧版监听端口未释放时不会启动 2.0，避免端口冲突。")
+              .font(.callout)
+              .foregroundStyle(.secondary)
+          }
+
+          loginItemGuidance(detection: detection)
+        }
+      }
+      .frame(maxWidth: .infinity, alignment: .leading)
+    }
+  }
+
+  private var legacyAppRunningCard: some View {
+    VStack(alignment: .leading, spacing: 8) {
+      Label(
+        "旧版 ShadowsocksX-NG 正在运行", systemImage: "exclamationmark.triangle.fill"
+      )
+      .foregroundStyle(.orange)
+      Text("请先退出旧版 app：它占用的 PAC 端口不会被后台服务的停用动作释放。")
+        .font(.callout)
+      Button("退出旧版应用") {
+        viewModel.quitLegacyApp()
+      }
+      .controlSize(.small)
+    }
+    .frame(maxWidth: .infinity, alignment: .leading)
+    .padding(12)
+    .background(.orange.opacity(0.12), in: RoundedRectangle(cornerRadius: 8))
+  }
+
+  // MARK: - 执行中 / 完成 / 失败
+
+  private var performingView: some View {
+    VStack(alignment: .leading, spacing: 12) {
+      ProgressView().controlSize(.small)
+      Text("正在停用旧版后台服务并清理系统代理…")
+        .font(.callout)
+        .foregroundStyle(.secondary)
+    }
+  }
+
+  private var completedView: some View {
+    ScrollView {
+      VStack(alignment: .leading, spacing: 12) {
+        if let report = viewModel.report {
+          if !report.bootedOutLabels.isEmpty {
+            Label(
+              "已停用 \(report.bootedOutLabels.count) 个旧版后台服务",
+              systemImage: "checkmark.circle.fill"
+            )
+            .foregroundStyle(.green)
+            ForEach(report.bootedOutLabels, id: \.self) { label in
+              Text(label).font(.callout).foregroundStyle(.secondary)
+            }
+          } else {
+            Label("没有发现需要停用的旧版后台服务", systemImage: "checkmark.circle")
+              .foregroundStyle(.secondary)
+          }
+          if !report.disabledLabels.isEmpty {
+            Text(
+              "已阻止 \(report.disabledLabels.count) 个残留配置在下次登录时自动加载。"
+            )
+            .font(.callout)
+          }
+          if !report.proxyServicesCleaned.isEmpty {
+            Text("已清理 \(report.proxyServicesCleaned.count) 个网络服务的旧版系统代理配置。")
+              .font(.callout)
+          }
+          if !report.proxyServicesUntouchedUnknownOwner.isEmpty {
+            Text(
+              "以下网络服务的代理配置不属于旧版，未改动："
+                + report.proxyServicesUntouchedUnknownOwner.joined(separator: "、")
+            )
+            .font(.callout)
+            .foregroundStyle(.orange)
+          }
+          if !report.confirmedFreePorts.isEmpty {
+            Text(
+              "端口 \(report.confirmedFreePorts.map(String.init).joined(separator: "、")) 已释放，2.0 代理正在启动。"
+            )
+            .font(.callout)
+          }
+          if !report.residue.isEmpty {
+            Divider()
+            Text("Legacy 数据全部保留，可随时回退。以下残留建议之后手动处理：")
+              .font(.callout)
+            ForEach(report.residue, id: \.label) { residue in
+              Text(
+                "• ~/Library/LaunchAgents/\(residue.label).plist"
+                  + residueDetailSuffix(residue)
+              )
+              .font(.callout)
+              .foregroundStyle(.secondary)
+            }
+          }
+          Divider()
+          loginItemGuidanceIfKnown()
+        }
+      }
+      .frame(maxWidth: .infinity, alignment: .leading)
+    }
+  }
+
+  private func failedView(_ reason: String) -> some View {
+    VStack(alignment: .leading, spacing: 12) {
+      Label("交接未完成", systemImage: "xmark.octagon.fill")
+        .foregroundStyle(.red)
+      Text(reason)
+        .font(.callout)
+      Text("已执行的动作不会回滚（已停用的服务保持停用）；解决上面的问题后可重新执行交接。")
+        .font(.callout)
+        .foregroundStyle(.secondary)
+      Button("重新检查") {
+        Task { await viewModel.refresh() }
+      }
+      .controlSize(.small)
+    }
+    .frame(maxWidth: .infinity, alignment: .leading)
+  }
+
+  // MARK: - 登录项指引（无编程停用路径，仅人工）
+
+  @ViewBuilder
+  private func loginItemGuidance(detection: LegacyHandoffDetection) -> some View {
+    stateSection(title: "旧版的开机自启动需要手动关闭") {
+      Text(
+        detection.legacyAppInstalled
+          ? "打开 系统设置 → 通用 → 登录项与扩展，移除 ShadowsocksX-NG（或其 LaunchHelper）条目；也可以打开旧版 app，在偏好设置中关闭「登录时启动」。"
+          : "若曾使用旧版的开机自启动：打开 系统设置 → 通用 → 登录项与扩展，移除 ShadowsocksX-NG（或其 LaunchHelper）条目。"
+      )
+      .font(.callout)
+      .foregroundStyle(.secondary)
+      Button("打开系统设置的登录项面板") {
+        openLoginItemsSettings()
+      }
+      .controlSize(.small)
+    }
+  }
+
+  @ViewBuilder
+  private func loginItemGuidanceIfKnown() -> some View {
+    if let detection = viewModel.detection {
+      loginItemGuidance(detection: detection)
+    }
+  }
+
+  // MARK: - 底部按钮
+
+  @ViewBuilder
+  private var footerButtons: some View {
+    HStack {
+      Button("关闭") { dismiss() }
+      Spacer()
+      if case .ready = viewModel.phase {
+        Button("切换到 2.0") {
+          Task { await viewModel.performHandoff() }
+        }
+        .keyboardShortcut(.defaultAction)
+        .disabled(!viewModel.canConfirm)
+      }
+    }
+  }
+
+  private func stateSection<Content: View>(
+    title: String?, @ViewBuilder content: () -> Content
+  ) -> some View {
+    VStack(alignment: .leading, spacing: 6) {
+      if let title {
+        Text(title)
+          .font(.headline)
+      }
+      content()
+    }
+    .frame(maxWidth: .infinity, alignment: .leading)
+    .padding(12)
+    .background(.quaternary.opacity(0.4), in: RoundedRectangle(cornerRadius: 8))
+  }
+
+  /// 残留 plist 的一行说明：活跃性必须读内容判断（2017 前的生成代码带
+  /// KeepAlive，会登录自启）；读不出内容时如实说明，不冒充休眠。
+  private func residueDescription(_ residue: LegacyAgentPlistResidue) -> String {
+    if !residue.contentReadable {
+      return "\(residue.label)：存在但内容无法读取，无法判断活跃性；交接将阻止其加载，建议之后手动检查删除"
+    }
+    return residue.isActiveForm
+      ? "\(residue.label)：含 KeepAlive/RunAtLoad，会在登录时自动运行；交接将阻止其再次加载，建议之后手动删除该文件"
+      : "\(residue.label)：休眠残留（登录时仅注册、不运行）；交接将阻止其再次加载"
+  }
+
+  private func residueDetailSuffix(_ residue: LegacyAgentPlistResidue) -> String {
+    if !residue.contentReadable { return "（内容无法读取）" }
+    return residue.isActiveForm ? "（含 KeepAlive/RunAtLoad，交接已阻止其加载）" : ""
+  }
+
+  private func openLoginItemsSettings() {
+    SMAppService.openSystemSettingsLoginItems()
+  }
+}
diff --git a/ShadowsocksX-NG2/App/LegacyHandoffViewModel.swift b/ShadowsocksX-NG2/App/LegacyHandoffViewModel.swift
new file mode 100644
index 00000000..6d07b8ab
--- /dev/null
+++ b/ShadowsocksX-NG2/App/LegacyHandoffViewModel.swift
@@ -0,0 +1,112 @@
+import Foundation
+
+/// Legacy 交接视图模型（issue #37）：驱动「切换到 2.0」第二阶段——确认前置
+/// （旧版 app 已退出）、执行白名单停用与系统代理清理，成功后启动 2.0 代理。
+/// 端口门禁失败、bootout 失败都不启动 2.0（显式失败呈现，无静默回退）。
+/// 与 ProxyRuntimeController 通过启停闭包解耦，便于测试。
+@MainActor
+final class LegacyHandoffViewModel: ObservableObject {
+  enum Phase: Equatable {
+    /// 尚未完成识别。
+    case idle
+    case ready
+    case performing
+    case completed
+    case failed(String)
+  }
+
+  @Published private(set) var detection: LegacyHandoffDetection?
+  @Published private(set) var phase: Phase = .idle
+  @Published private(set) var report: LegacyHandoffReport?
+  @Published private(set) var handoffCompleted: Bool
+  /// 引导退出旧版 app 失败时的呈现面。
+  @Published var presentedError: String?
+
+  /// 交接成功后启动 2.0 代理（生产接线 ProxyRuntimeController.setProxyEnabled）；
+  /// 执行前若 2.0 代理在跑则先停（重跑交接时 2.0 可能持有端口）。
+  var startProxy: (() async -> Void)?
+  var stopProxy: (() async -> Void)?
+
+  private let service: LegacyHandoffService
+  private let appController: LegacyAppControlling
+
+  init(
+    service: LegacyHandoffService = LegacyHandoffService(
+      launchctl: ProcessLaunchctlController(),
+      plistInspector: FileSystemLegacyAgentPlistInspector(),
+      appController: WorkspaceLegacyAppController(),
+      portsProvider: UserDefaultsLegacyListenPortsProvider(),
+      occupancyProbe: SystemPortOccupancyProbe(),
+      proxyCleaner: SystemConfigurationLegacyProxyCleaner(),
+      marker: UserDefaultsLegacyHandoffMarkerStore()),
+    appController: LegacyAppControlling = WorkspaceLegacyAppController()
+  ) {
+    self.service = service
+    self.appController = appController
+    handoffCompleted = service.isCompleted()
+  }
+
+  /// 只读识别（launchctl print 退出码 + plist 存在性 + 端口来源），不改任何
+  /// launchd 状态、不动 Legacy 数据；process 派发避免阻塞主线程。
+  func refresh() async {
+    handoffCompleted = service.isCompleted()
+    let detected = await Task.detached(priority: .userInitiated) {
+      self.service.detect()
+    }.value
+    detection = detected
+    if phase != .performing {
+      phase = .ready
+    }
+  }
+
+  /// 确认按钮的可用条件：识别完成、无未知状态、旧版 app 已退出、确有可停用
+  /// 的痕迹（无可停用内容时不提供确认，避免无意义地走一遍流程）。
+  var canConfirm: Bool {
+    guard let detection, phase != .performing else { return false }
+    guard detection.printFailures.isEmpty, !detection.legacyAppRunning else { return false }
+    let plan = LegacyHandoffPlan.make(from: detection)
+    return !plan.actions.isEmpty
+  }
+
+  var hasUnknownState: Bool {
+    detection?.printFailures.isEmpty == false
+  }
+
+  /// 仍存在旧版运行痕迹（已加载 job、残留 plist 或旧版 app 本体）——主窗口
+  /// 据此在交接完成后持续提供「Legacy 交接与残留」入口（D12「后续检测到残
+  /// 留提示用户处理」）。
+  var hasLegacyEvidence: Bool {
+    guard let detection else { return false }
+    return !detection.loadedLabels.isEmpty
+      || detection.plists.contains { $0.fileExists }
+      || detection.legacyAppRunning
+  }
+
+  func performHandoff() async {
+    guard canConfirm else { return }
+    phase = .performing
+    await stopProxy?()
+    do {
+      let handoffReport = try await service.performHandoff()
+      report = handoffReport
+      handoffCompleted = true
+      phase = .completed
+      // 端口门禁通过后才启动 2.0（service 内部已确认）；启动失败在代理控制
+      // 器状态与菜单栏点名呈现，不影响交接完成态。
+      await startProxy?()
+    } catch let error as LegacyHandoffError {
+      phase = .failed(error.presentedReason)
+    } catch {
+      phase = .failed(String(describing: error))
+    }
+  }
+
+  /// 引导退出旧版 app（优雅退出，等价用户点退出菜单）；退出后自动重新识别。
+  func quitLegacyApp() {
+    guard appController.requestGracefulQuit() else {
+      presentedError = "无法向旧版 ShadowsocksX-NG 发送退出请求，请手动退出后重试"
+      return
+    }
+    Task { await refresh() }
+  }
+}
diff --git a/ShadowsocksX-NG2/App/LegacyImportSheet.swift b/ShadowsocksX-NG2/App/LegacyImportSheet.swift
index 61c642fa..e5c8a0dc 100644
--- a/ShadowsocksX-NG2/App/LegacyImportSheet.swift
+++ b/ShadowsocksX-NG2/App/LegacyImportSheet.swift
@@ -5,6 +5,9 @@ import SwiftUI
 /// named skipped records, identity regeneration, and migration warnings.
 struct LegacyImportSheet: View {
   @ObservedObject var viewModel: CatalogViewModel
+  /// 导入成功后的「切换到 2.0」第二阶段入口（issue #37：交接与导入分离，
+  /// 由用户显式发起）；nil 时隐藏。
+  var onHandoffRequested: (() -> Void)?
   @Environment(\.dismiss) private var dismiss
 
   @State private var isImporting = false
@@ -38,6 +41,9 @@ struct LegacyImportSheet: View {
       HStack {
         Button("暂不导入") { dismiss() }
         Spacer()
+        if viewModel.legacyImportReport != nil, let onHandoffRequested {
+          Button("切换到 2.0…") { onHandoffRequested() }
+        }
         Button(viewModel.legacyImportCompleted ? "再次导入" : "导入") {
           importLegacy()
         }
diff --git a/ShadowsocksX-NG2/App/MainWindowView.swift b/ShadowsocksX-NG2/App/MainWindowView.swift
index 34c60f66..9923571e 100644
--- a/ShadowsocksX-NG2/App/MainWindowView.swift
+++ b/ShadowsocksX-NG2/App/MainWindowView.swift
@@ -16,6 +16,8 @@ struct MainWindowView: View {
   @ObservedObject var proxyController: ProxyRuntimeController
   let eventStore: RuntimeEventStore
 
+  @StateObject private var legacyHandoffModel = LegacyHandoffViewModel()
+
   @State private var pane: Pane = .servers
   @State private var renameTarget: NodeID?
   @State private var renameText = ""
@@ -26,6 +28,7 @@ struct MainWindowView: View {
   @State private var showImportURLSheet = false
   @State private var showQRImportSheet = false
   @State private var showLegacyImportSheet = false
+  @State private var showLegacyHandoffSheet = false
   @State private var didOfferLegacyImport = false
   @State private var rootDropHovering = false
 
@@ -85,7 +88,22 @@ struct MainWindowView: View {
       QRImportSheet(viewModel: viewModel)
     }
     .sheet(isPresented: $showLegacyImportSheet) {
-      LegacyImportSheet(viewModel: viewModel)
+      LegacyImportSheet(
+        viewModel: viewModel,
+        onHandoffRequested: {
+          showLegacyImportSheet = false
+          showLegacyHandoffSheet = true
+        })
+    }
+    .sheet(isPresented: $showLegacyHandoffSheet) {
+      LegacyHandoffSheet(viewModel: legacyHandoffModel)
+        .task {
+          // 交接成功后经正常启停入口启动 2.0（健康门禁、系统代理授权写入
+          // 全部走 #29 路径）；重跑交接前先停 2.0 以释放端口。
+          legacyHandoffModel.stopProxy = { await proxyController.setProxyEnabled(false) }
+          legacyHandoffModel.startProxy = { await proxyController.setProxyEnabled(true) }
+          await legacyHandoffModel.refresh()
+        }
     }
     .sheet(
       item: Binding(
@@ -99,6 +117,10 @@ struct MainWindowView: View {
       didOfferLegacyImport = true
       showLegacyImportSheet = true
     }
+    .task {
+      // 交接入口可见性依赖交接完成标记（issue #37）。
+      await legacyHandoffModel.refresh()
+    }
   }
 
   // MARK: - 侧栏（分区切换 + 树 / 诊断摘要）
@@ -252,6 +274,16 @@ struct MainWindowView: View {
             showLegacyImportSheet = true
           }
         }
+        if viewModel.legacyImportAvailable || !legacyHandoffModel.handoffCompleted
+          || legacyHandoffModel.hasLegacyEvidence
+        {
+          Button(
+            legacyHandoffModel.handoffCompleted
+              ? "Legacy 交接与残留…" : "切换到 2.0（交接旧版服务）…"
+          ) {
+            showLegacyHandoffSheet = true
+          }
+        }
         Divider()
         Button("新建分组…") {
           newGroupParent = viewModel.importTargetParent(for: viewModel.selectedNodeID)
diff --git a/ShadowsocksX-NG2/App/SystemConfigurationLegacyProxyCleaner.swift b/ShadowsocksX-NG2/App/SystemConfigurationLegacyProxyCleaner.swift
new file mode 100644
index 00000000..5cd0dc09
--- /dev/null
+++ b/ShadowsocksX-NG2/App/SystemConfigurationLegacyProxyCleaner.swift
@@ -0,0 +1,203 @@
+import Foundation
+import Security
+import SystemConfiguration
+
+/// Legacy 写入的系统代理清理（issue #37）：读取当前网络位置每个服务的
+/// Proxies 字典并按 Legacy 特征值判定归属，只改写判定为 Legacy 的服务
+/// （禁用全部代理面、移除端点值）；空配置跳过；未知所有者原样保留并点名
+/// 返回，绝不覆盖。事务纪律与 SystemConfigurationProxyController 一致：
+/// 写入失败回滚到本次操作前状态。实现只抛 LegacyHandoffError.proxyCleanFailed。
+final class SystemConfigurationLegacyProxyCleaner: LegacyProxyCleaning {
+  private struct ServiceSnapshot {
+    let id: String
+    let proxyProtocol: SCNetworkProtocol
+    let configuration: Data?
+  }
+
+  func cleanLegacyOwnedProxy(ports: LegacyListenPorts) throws -> LegacyProxyCleanOutcome {
+    do {
+      return try withPreferences { preferences in
+        let (legacyServices, unknownOwnerServiceIDs) =
+          try classifyServices(in: preferences, ports: ports)
+        guard !legacyServices.isEmpty else {
+          return LegacyProxyCleanOutcome(
+            cleanedServiceIDs: [], unknownOwnerServiceIDs: unknownOwnerServiceIDs)
+        }
+        let cleanedServiceIDs = try clean(legacyServices, in: preferences)
+        return LegacyProxyCleanOutcome(
+          cleanedServiceIDs: cleanedServiceIDs,
+          unknownOwnerServiceIDs: unknownOwnerServiceIDs)
+      }
+    } catch let error as LegacyHandoffError {
+      throw error
+    } catch {
+      throw LegacyHandoffError.proxyCleanFailed(detail: describe(error))
+    }
+  }
+
+  // MARK: - SystemConfiguration 管道（与 SystemConfigurationProxyController 同纪律）
+
+  /// 归属分类（只读）：Legacy 服务捕获原字典供清理投影；未知所有者点名返回。
+  private func classifyServices(
+    in preferences: SCPreferences, ports: LegacyListenPorts
+  ) throws -> (
+    legacy: [(ServiceSnapshot, [String: Any])], unknownOwnerIDs: [String]
+  ) {
+    let services = try serviceSnapshots(in: preferences)
+    guard !services.isEmpty else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.noProxyServices.presentedReason)
+    }
+    var legacyServices: [(ServiceSnapshot, [String: Any])] = []
+    var unknownOwnerIDs: [String] = []
+    for service in services {
+      let dictionary = try readableDictionary(
+        from: service.configuration, serviceID: service.id)
+      switch LegacySystemProxySignature.classify(dictionary, ports: ports) {
+      case .none:
+        continue
+      case .legacy:
+        legacyServices.append((service, dictionary))
+      case .other:
+        unknownOwnerIDs.append(service.id)
+      }
+    }
+    return (legacyServices, unknownOwnerIDs)
+  }
+
+  /// 写入并提交；失败回滚到本次操作前状态。
+  private func clean(
+    _ legacyServices: [(ServiceSnapshot, [String: Any])], in preferences: SCPreferences
+  ) throws -> [String] {
+    try SCPreferencesLockOrThrow(preferences)
+    defer { SCPreferencesUnlock(preferences) }
+    do {
+      for (service, dictionary) in legacyServices {
+        let cleaned = LegacySystemProxySignature.cleaned(dictionary)
+        guard SCNetworkProtocolSetConfiguration(service.proxyProtocol, cleaned as CFDictionary)
+        else {
+          throw LegacyHandoffError.proxyCleanFailed(
+            detail: SystemProxyError.cannotWriteService(service.id).presentedReason)
+        }
+      }
+      try commitAndApply(preferences)
+    } catch {
+      let rollbackSucceeded = rollback(legacyServices, in: preferences)
+      var detail = describe(error)
+      if !rollbackSucceeded {
+        detail += "；系统代理变更回滚失败：\(systemConfigurationError())"
+      }
+      throw LegacyHandoffError.proxyCleanFailed(detail: detail)
+    }
+    return legacyServices.map { $0.0.id }
+  }
+
+  private func withPreferences(
+    _ body: (SCPreferences) throws -> LegacyProxyCleanOutcome
+  ) throws -> LegacyProxyCleanOutcome {
+    var authorization: AuthorizationRef?
+    let flags: AuthorizationFlags = [.interactionAllowed, .extendRights, .preAuthorize]
+    let authorizationStatus = AuthorizationCreate(nil, nil, flags, &authorization)
+    guard authorizationStatus == errAuthorizationSuccess, let authorization else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.authorizationFailed(authorizationStatus).presentedReason)
+    }
+    defer { AuthorizationFree(authorization, []) }
+
+    guard
+      let preferences = SCPreferencesCreateWithAuthorization(
+        nil, "ShadowsocksX-NG" as CFString, nil, authorization)
+    else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.preferencesUnavailable.presentedReason)
+    }
+    return try body(preferences)
+  }
+
+  private func serviceSnapshots(in preferences: SCPreferences) throws -> [ServiceSnapshot] {
+    guard let set = SCNetworkSetCopyCurrent(preferences) else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.noCurrentNetworkSet.presentedReason)
+    }
+    guard let services = SCNetworkSetCopyServices(set) as? [SCNetworkService] else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.noProxyServices.presentedReason)
+    }
+    return try services.compactMap { service in
+      guard
+        let serviceID = SCNetworkServiceGetServiceID(service) as String?,
+        let proxyProtocol = SCNetworkServiceCopyProtocol(service, kSCNetworkProtocolTypeProxies)
+      else { return nil }
+      return ServiceSnapshot(
+        id: serviceID,
+        proxyProtocol: proxyProtocol,
+        configuration: try propertyListData(
+          from: SCNetworkProtocolGetConfiguration(proxyProtocol), serviceID: serviceID))
+    }
+  }
+
+  private func rollback(
+    _ services: [(ServiceSnapshot, [String: Any])], in preferences: SCPreferences
+  ) -> Bool {
+    for (service, original) in services {
+      guard SCNetworkProtocolSetConfiguration(service.proxyProtocol, original as CFDictionary)
+      else {
+        return false
+      }
+    }
+    return SCPreferencesCommitChanges(preferences) && SCPreferencesApplyChanges(preferences)
+  }
+
+  private func readableDictionary(
+    from data: Data?, serviceID: String
+  ) throws -> [String: Any] {
+    guard let data else { return [:] }
+    guard
+      let propertyList = try? PropertyListSerialization.propertyList(
+        from: data, options: [], format: nil),
+      let dictionary = propertyList as? [String: Any]
+    else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.invalidStoredConfiguration(serviceID).presentedReason)
+    }
+    return dictionary
+  }
+
+  private func propertyListData(
+    from value: CFPropertyList?, serviceID: String
+  ) throws -> Data? {
+    guard let value else { return nil }
+    guard let dictionary = value as? [String: Any] else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: SystemProxyError.unreadableService(serviceID).presentedReason)
+    }
+    return try PropertyListSerialization.data(
+      fromPropertyList: dictionary, format: .binary, options: 0)
+  }
+
+  private func commitAndApply(_ preferences: SCPreferences) throws {
+    guard SCPreferencesCommitChanges(preferences) else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: "提交失败：\(systemConfigurationError())")
+    }
+    guard SCPreferencesApplyChanges(preferences) else {
+      throw LegacyHandoffError.proxyCleanFailed(
+        detail: "应用失败：\(systemConfigurationError())")
+    }
+  }
+
+  private func describe(_ error: Error) -> String {
+    (error as? SystemProxyError)?.presentedReason ?? String(describing: error)
+  }
+
+  private func systemConfigurationError() -> String {
+    String(cString: SCErrorString(SCError()))
+  }
+}
+
+private func SCPreferencesLockOrThrow(_ preferences: SCPreferences) throws {
+  guard SCPreferencesLock(preferences, true) else {
+    throw LegacyHandoffError.proxyCleanFailed(
+      detail: SystemProxyError.preferencesBusy.presentedReason)
+  }
+}
diff --git a/ShadowsocksX-NG2/Domain/LegacyHandoff.swift b/ShadowsocksX-NG2/Domain/LegacyHandoff.swift
new file mode 100644
index 00000000..527d5fe1
--- /dev/null
+++ b/ShadowsocksX-NG2/Domain/LegacyHandoff.swift
@@ -0,0 +1,677 @@
+import Darwin
+import Foundation
+
+/// Legacy 交接（spec #21 D12，issue #37）：与导入分离的第二阶段。用户明确确认
+/// 「切换到 2.0」后，按硬编码白名单停用三个 Legacy launchd label（全历史无变
+/// 体，见 docs/research/wayfinder-issue-17-legacy-handoff.md §1）——不泛匹配、
+/// 不 pkill；前置确认旧版 app 已退出（其 GUI 进程持有 PAC 端口，bootout 不释
+/// 放），端口释放确认通过后才允许启动 2.0；Legacy 数据一律不删除，残留仅提示。
+enum LegacyLaunchAgentLabel: String, CaseIterable, Sendable {
+  case local = "com.qiuyuzhou.shadowsocksX-NG.local"
+  case http = "com.qiuyuzhou.shadowsocksX-NG.http"
+  case kcptun = "com.qiuyuzhou.shadowsocksX-NG.kcptun"
+}
+
+/// Legacy 三端口的配置值（只读读取，属于 Legacy 数据——只读、不删改）。
+struct LegacyListenPorts: Equatable, Sendable {
+  var socksPort: Int = 1086
+  var httpPort: Int = 1087
+  var pacPort: Int = 1089
+  var socksAddress: String = "127.0.0.1"
+}
+
+protocol LegacyListenPortsProviding: Sendable {
+  func currentPorts() -> LegacyListenPorts
+}
+
+/// 从 Legacy defaults 域读取端口（inventory §1：端口不在 LaunchAgent plist 内，
+/// 用户自定义值在 defaults）。缺失或无效回落出厂三端口，不改写任何值。
+/// UserDefaults 线程安全（Apple 文档），Sendable 依存性核对为安全。
+struct UserDefaultsLegacyListenPortsProvider: LegacyListenPortsProviding, @unchecked Sendable {
+  static let legacyBundleIdentifier = "com.qiuyuzhou.ShadowsocksX-NG"
+
+  let defaults: UserDefaults
+  let bundleIdentifier: String
+
+  init(
+    defaults: UserDefaults = .standard,
+    bundleIdentifier: String = UserDefaultsLegacyListenPortsProvider.legacyBundleIdentifier
+  ) {
+    self.defaults = defaults
+    self.bundleIdentifier = bundleIdentifier
+  }
+
+  func currentPorts() -> LegacyListenPorts {
+    let domain = defaults.persistentDomain(forName: bundleIdentifier) ?? [:]
+    func port(_ key: String, fallback: Int) -> Int {
+      guard let number = domain[key] as? NSNumber else { return fallback }
+      let value = number.intValue
+      return (1...65_535).contains(value) ? value : fallback
+    }
+    let address = (domain["LocalSocks5.ListenAddress"] as? String)?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return LegacyListenPorts(
+      socksPort: port("LocalSocks5.ListenPort", fallback: 1086),
+      httpPort: port("LocalHTTP.ListenPort", fallback: 1087),
+      pacPort: port("PacServer.ListenPort", fallback: 1089),
+      socksAddress: (address?.isEmpty == false) ? address! : "127.0.0.1")
+  }
+}
+
+// MARK: - 系统代理归属判定（特征值）
+
+/// Legacy 特征判定结果：`.none` 无启用代理；`.legacy` 全部启用面与 Legacy 写
+/// 入特征匹配；`.other` 存在非 Legacy 特征（未知所有者，不覆盖——D12）。
+enum LegacyProxyOwnershipClass: Equatable, Sendable {
+  case none
+  case legacy
+  case other
+}
+
+/// 系统代理无所有者标记（wayfinder #17 §5.1），归属 = 特征值匹配。特征镜像
+/// Legacy 自身 `proxy_conf_helper` off 模式的判定（main.m:191-202）：本地 PAC
+/// URL 恰为 `http://localhost:<pacPort>/proxy.pac`（host 硬编码 localhost），
+/// SOCKS 为其监听地址与端口，HTTP/HTTPS 为 Privoxy 地址与端口。任一启用面不
+/// 匹配（含混合）即按未知所有者处理。2.0 自身写 `/v1/proxy.pac`，不会碰撞。
+enum LegacySystemProxySignature {
+  static let pacPath = "/proxy.pac"
+  static let httpProxy = "HTTPProxy"
+  static let httpPort = "HTTPPort"
+  static let httpsProxy = "HTTPSProxy"
+  static let httpsPort = "HTTPSPort"
+
+  /// Legacy off 模式写入的静止形态：全部禁用。
+  static let emptyDisabled: [String: Any] = [
+    SystemProxyPropertyList.httpEnabled: 0,
+    SystemProxyPropertyList.httpsEnabled: 0,
+    SystemProxyPropertyList.pacEnabled: 0,
+    SystemProxyPropertyList.socksEnabled: 0,
+    SystemProxyPropertyList.exceptionsList: [String](),
+  ]
+
+  static func legacyPACURL(port: Int) -> String {
+    "http://localhost:\(port)\(pacPath)"
+  }
+
+  static func classify(
+    _ dictionary: [String: Any], ports: LegacyListenPorts
+  ) -> LegacyProxyOwnershipClass {
+    var sawEnabledFacet = false
+
+    if intValue(dictionary[SystemProxyPropertyList.pacEnabled]) == 1 {
+      sawEnabledFacet = true
+      guard
+        stringValue(dictionary[SystemProxyPropertyList.pacURL]) == legacyPACURL(port: ports.pacPort)
+      else { return .other }
+    }
+    if intValue(dictionary[SystemProxyPropertyList.socksEnabled]) == 1 {
+      sawEnabledFacet = true
+      guard
+        isEquivalentHost(
+          stringValue(dictionary[SystemProxyPropertyList.socksProxy]), to: ports.socksAddress),
+        intValue(dictionary[SystemProxyPropertyList.socksPort]) == ports.socksPort
+      else { return .other }
+    }
+    if intValue(dictionary[SystemProxyPropertyList.httpEnabled]) == 1 {
+      sawEnabledFacet = true
+      guard
+        isLoopbackHost(stringValue(dictionary[httpProxy])),
+        intValue(dictionary[httpPort]) == ports.httpPort
+      else { return .other }
+    }
+    if intValue(dictionary[SystemProxyPropertyList.httpsEnabled]) == 1 {
+      sawEnabledFacet = true
+      guard
+        isLoopbackHost(stringValue(dictionary[httpsProxy])),
+        intValue(dictionary[httpsPort]) == ports.httpPort
+      else { return .other }
+    }
+    return sawEnabledFacet ? .legacy : .none
+  }
+
+  /// 清理投影：只处理**启用**且归属匹配的代理面——禁用面的端点值可能是
+  /// 用户或其他软件的静止数据（Legacy helper 整字典替换的写入形态下不会与
+  /// Legacy 特征共存，但手工混入可能），一律不动；绕过列表等其余键保留。
+  /// 幂等。
+  static func cleaned(_ dictionary: [String: Any]) -> [String: Any] {
+    var result = dictionary
+    let enabledFacets: [(enableKey: String, endpointKeys: [String])] = [
+      (
+        SystemProxyPropertyList.pacEnabled,
+        [SystemProxyPropertyList.pacURL, SystemProxyPropertyList.pacJavaScript]
+      ),
+      (
+        SystemProxyPropertyList.socksEnabled,
+        [SystemProxyPropertyList.socksProxy, SystemProxyPropertyList.socksPort]
+      ),
+      (SystemProxyPropertyList.httpEnabled, [httpProxy, httpPort]),
+      (SystemProxyPropertyList.httpsEnabled, [httpsProxy, httpsPort]),
+    ]
+    for facet in enabledFacets {
+      guard intValue(dictionary[facet.enableKey]) == 1 else { continue }
+      result[facet.enableKey] = 0
+      for key in facet.endpointKeys {
+        result.removeValue(forKey: key)
+      }
+    }
+    return result
+  }
+
+  private static let loopbackWrites: Set<String> = ["127.0.0.1", "localhost", "::1"]
+
+  /// 127.0.0.1 / localhost / ::1 视为同一回环写法；其余按大小写不敏感全等。
+  static func isEquivalentHost(_ actual: String?, to expected: String) -> Bool {
+    guard let actual, !actual.isEmpty else { return false }
+    let normalizedActual = actual.lowercased()
+    let normalizedExpected = expected.lowercased()
+    if normalizedActual == normalizedExpected { return true }
+    return loopbackWrites.contains(normalizedActual)
+      && loopbackWrites.contains(normalizedExpected)
+  }
+
+  static func isLoopbackHost(_ actual: String?) -> Bool {
+    guard let actual, !actual.isEmpty else { return false }
+    return loopbackWrites.contains(actual.lowercased())
+  }
+
+  private static func intValue(_ value: Any?) -> Int? {
+    (value as? NSNumber)?.intValue
+  }
+
+  private static func stringValue(_ value: Any?) -> String? {
+    value as? String
+  }
+}
+
+// MARK: - launchctl 命令缝
+
+struct LaunchctlOutcome: Equatable, Sendable {
+  let exitCode: Int32
+  let stderr: String
+}
+
+/// `launchctl print` 的状态判定只依赖退出码（man 明文 print 输出结构非 API，
+/// 不解析文本）：0 已加载、113 不存在、其余未知。
+enum LaunchctlServiceState: Equatable, Sendable {
+  case loaded
+  case notLoaded
+  case unknown(detail: String)
+}
+
+protocol LaunchctlControlling: Sendable {
+  func serviceState(label: String) -> LaunchctlServiceState
+  func bootout(label: String) -> LaunchctlOutcome
+  func disable(label: String) -> LaunchctlOutcome
+  func kill(label: String, signal: Int32) -> LaunchctlOutcome
+}
+
+/// 系统实现：gui 域按 service target 操作（`gui/<uid>/<label>`），bootout 不
+/// 需要 plist 文件存在，覆盖「job 已加载但 plist 缺失」的错位形态。
+struct ProcessLaunchctlController: LaunchctlControlling {
+  static let executableURL = URL(fileURLWithPath: "/bin/launchctl")
+
+  func serviceState(label: String) -> LaunchctlServiceState {
+    let outcome = Self.run(["print", Self.serviceTarget(label)])
+    switch outcome.exitCode {
+    case 0: return .loaded
+    case 113: return .notLoaded
+    default: return .unknown(detail: outcome.stderr)
+    }
+  }
+
+  func bootout(label: String) -> LaunchctlOutcome {
+    Self.run(["bootout", Self.serviceTarget(label)])
+  }
+
+  func disable(label: String) -> LaunchctlOutcome {
+    // 跨启动持久的 override：阻止残留 plist（含 KeepAlive 形态）在下次登录
+    // 复活；Legacy 自身用 `load -w`，重装可自行覆盖 disabled 状态。
+    Self.run(["disable", Self.serviceTarget(label)])
+  }
+
+  func kill(label: String, signal: Int32) -> LaunchctlOutcome {
+    Self.run(["kill", String(signal), Self.serviceTarget(label)])
+  }
+
+  private static func serviceTarget(_ label: String) -> String {
+    "gui/\(getuid())/\(label)"
+  }
+
+  static func run(_ arguments: [String]) -> LaunchctlOutcome {
+    let process = Process()
+    process.executableURL = executableURL
+    process.arguments = arguments
+    let stdoutPipe = Pipe()
+    let stderrPipe = Pipe()
+    process.standardOutput = stdoutPipe
+    process.standardError = stderrPipe
+    do {
+      try process.run()
+    } catch {
+      return LaunchctlOutcome(exitCode: -1, stderr: String(describing: error))
+    }
+    // print 的 stdout 可能超过管道缓冲：并发排空，避免顺序读死锁。
+    let stderrQueue = DispatchQueue.global(qos: .utility)
+    var stderrData = Data()
+    let group = DispatchGroup()
+    group.enter()
+    stderrQueue.async {
+      stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()
+      group.leave()
+    }
+    _ = stdoutPipe.fileHandleForReading.readDataToEndOfFile()
+    group.wait()
+    process.waitUntilExit()
+    return LaunchctlOutcome(
+      exitCode: process.terminationStatus,
+      stderr: String(data: stderrData, encoding: .utf8) ?? "")
+  }
+}
+
+// MARK: - 残留 plist 检查
+
+/// 磁盘残留 plist 状态。活跃性必须读内容判断：2017 前的生成代码带 KeepAlive，
+/// 这类残留每次登录自动拉起并在退出后重启（wayfinder #17 §2.2）。
+struct LegacyAgentPlistResidue: Equatable, Sendable {
+  let label: String
+  let fileExists: Bool
+  let keepAlive: Bool
+  let runAtLoad: Bool
+  var contentReadable: Bool = true
+
+  var isActiveForm: Bool { keepAlive || runAtLoad }
+}
+
+protocol LegacyAgentPlistInspecting: Sendable {
+  func residue(for label: String) -> LegacyAgentPlistResidue
+}
+
+struct FileSystemLegacyAgentPlistInspector: LegacyAgentPlistInspecting {
+  static var launchAgentsDirectory: URL {
+    FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(
+      "Library/LaunchAgents", isDirectory: true)
+  }
+
+  func residue(for label: String) -> LegacyAgentPlistResidue {
+    let url = Self.launchAgentsDirectory.appendingPathComponent(label + ".plist")
+    guard FileManager.default.fileExists(atPath: url.path) else {
+      return LegacyAgentPlistResidue(
+        label: label, fileExists: false, keepAlive: false, runAtLoad: false)
+    }
+    guard
+      let data = try? Data(contentsOf: url),
+      let plist = try? PropertyListSerialization.propertyList(
+        from: data, options: [], format: nil) as? [String: Any]
+    else {
+      return LegacyAgentPlistResidue(
+        label: label, fileExists: true, keepAlive: false, runAtLoad: false,
+        contentReadable: false)
+    }
+    return LegacyAgentPlistResidue(
+      label: label,
+      fileExists: true,
+      keepAlive: Self.isActiveFlag(plist["KeepAlive"]),
+      runAtLoad: Self.isActiveFlag(plist["RunAtLoad"]))
+  }
+
+  /// KeepAlive 可以是布尔，也可以是条件字典；非 false 即视为活跃形态。
+  private static func isActiveFlag(_ value: Any?) -> Bool {
+    if let number = value as? NSNumber { return number.boolValue }
+    if value is [String: Any] { return true }
+    return false
+  }
+}
+
+// MARK: - 旧版 app 检测缝
+
+protocol LegacyAppControlling: Sendable {
+  func isRunning() -> Bool
+  func isInstalled() -> Bool
+  func requestGracefulQuit() -> Bool
+}
+
+// MARK: - 检测、计划与报告
+
+struct LegacyHandoffDetection: Equatable, Sendable {
+  let loadedLabels: [String]
+  /// print 退出码既非 0 也非 113 的 label（状态未知，必须中止而非猜测）。
+  let printFailures: [String]
+  let plists: [LegacyAgentPlistResidue]
+  let legacyAppRunning: Bool
+  let legacyAppInstalled: Bool
+  let ports: LegacyListenPorts
+}
+
+enum LegacyHandoffAction: Equatable, Sendable {
+  case bootout(label: String)
+  case disable(label: String)
+}
+
+struct LegacyHandoffPlan: Equatable, Sendable {
+  let actions: [LegacyHandoffAction]
+  let residue: [LegacyAgentPlistResidue]
+
+  static func make(from detection: LegacyHandoffDetection) -> LegacyHandoffPlan {
+    var actions: [LegacyHandoffAction] = []
+    var residue: [LegacyAgentPlistResidue] = []
+    for label in LegacyLaunchAgentLabel.allCases {
+      if detection.loadedLabels.contains(label.rawValue) {
+        actions.append(.bootout(label: label.rawValue))
+      }
+      if let plist = detection.plists.first(where: { $0.label == label.rawValue }),
+        plist.fileExists
+      {
+        residue.append(plist)
+        actions.append(.disable(label: label.rawValue))
+      }
+    }
+    return LegacyHandoffPlan(actions: actions, residue: residue)
+  }
+}
+
+struct LegacyHandoffReport: Equatable, Sendable {
+  let bootedOutLabels: [String]
+  let killedLabels: [String]
+  let disabledLabels: [String]
+  let residue: [LegacyAgentPlistResidue]
+  let proxyServicesCleaned: [String]
+  let proxyServicesUntouchedUnknownOwner: [String]
+  let confirmedFreePorts: [Int]
+}
+
+enum LegacyHandoffError: Error, Equatable {
+  case legacyAppRunning
+  case detectionFailed(detail: String)
+  case proxyCleanFailed(detail: String)
+  case bootoutFailed(label: String, detail: String)
+  case disableFailed(label: String, detail: String)
+  case portsNotReleased(occupied: [String])
+
+  var presentedReason: String {
+    switch self {
+    case .legacyAppRunning:
+      "请先退出旧版 ShadowsocksX-NG app（它占用着 PAC 端口，卸载后台服务不会释放），再执行交接"
+    case .detectionFailed(let detail):
+      "无法确认旧版后台服务状态，已中止交接：\(detail)"
+    case .proxyCleanFailed(let detail):
+      "系统代理清理未完成，已中止且未改动任何旧版后台服务：\(detail)"
+    case .bootoutFailed(let label, let detail):
+      "无法停用旧版后台服务 \(label)：\(detail)"
+    case .disableFailed(let label, let detail):
+      "无法阻止旧版后台服务 \(label) 在下次登录时自动加载：\(detail)"
+    case .portsNotReleased(let occupied):
+      "旧版监听端口未释放，2.0 未启动：" + occupied.joined(separator: "、")
+    }
+  }
+}
+
+// MARK: - 系统代理清理缝
+
+struct LegacyProxyCleanOutcome: Equatable, Sendable {
+  let cleanedServiceIDs: [String]
+  let unknownOwnerServiceIDs: [String]
+}
+
+protocol LegacyProxyCleaning: Sendable {
+  /// 只改写归属判定为 Legacy 的网络服务；未知所有者原样保留并点名返回。
+  func cleanLegacyOwnedProxy(ports: LegacyListenPorts) throws -> LegacyProxyCleanOutcome
+}
+
+// MARK: - 完成标记
+
+protocol LegacyHandoffMarkerStoring: Sendable {
+  func isCompleted() -> Bool
+  func setCompleted(_ completed: Bool) throws
+}
+
+struct UserDefaultsLegacyHandoffMarkerStore: LegacyHandoffMarkerStoring, @unchecked Sendable {
+  static let key = "legacyHandoff.completed"
+
+  let defaults: UserDefaults
+
+  init(defaults: UserDefaults = .standard) {
+    self.defaults = defaults
+  }
+
+  func isCompleted() -> Bool {
+    defaults.bool(forKey: Self.key)
+  }
+
+  func setCompleted(_ completed: Bool) throws {
+    if completed {
+      defaults.set(true, forKey: Self.key)
+    } else {
+      defaults.removeObject(forKey: Self.key)
+    }
+  }
+}
+
+// MARK: - 交接服务
+
+/// 交接时序（wayfinder #17 §8）：前置退出检查 → 识别 → 系统代理清理（授权在
+/// 最前，失败即零影响中止）→ 白名单 bootout（print 退出码验证，kill 有文档
+/// 后备）→ 残留 plist disable → 端口释放门禁 → 写完成标记。启动 2.0 属于交
+/// 接之后的独立动作，端口门禁失败即不启动。
+struct LegacyHandoffService: Sendable {
+  let launchctl: LaunchctlControlling
+  let plistInspector: LegacyAgentPlistInspecting
+  let appController: LegacyAppControlling
+  let portsProvider: LegacyListenPortsProviding
+  let occupancyProbe: PortOccupancyProbing
+  let proxyCleaner: LegacyProxyCleaning
+  let marker: LegacyHandoffMarkerStoring
+  var portPollAttempts: Int = 20
+  var portPollIntervalNanoseconds: UInt64 = 500_000_000
+  var removalVerifyAttempts: Int = 5
+  var removalVerifyIntervalNanoseconds: UInt64 = 200_000_000
+
+  func isCompleted() -> Bool {
+    marker.isCompleted()
+  }
+
+  /// 只读识别（确认前展示状态用）；不写任何 launchd 状态、不动 Legacy 数据。
+  func detect() -> LegacyHandoffDetection {
+    var loadedLabels: [String] = []
+    var printFailures: [String] = []
+    for label in LegacyLaunchAgentLabel.allCases {
+      switch launchctl.serviceState(label: label.rawValue) {
+      case .loaded:
+        loadedLabels.append(label.rawValue)
+      case .notLoaded:
+        break
+      case .unknown(let detail):
+        printFailures.append("\(label.rawValue)（\(detail)）")
+      }
+    }
+    let plists = LegacyLaunchAgentLabel.allCases.map { label in
+      plistInspector.residue(for: label.rawValue)
+    }
+    return LegacyHandoffDetection(
+      loadedLabels: loadedLabels,
+      printFailures: printFailures,
+      plists: plists,
+      legacyAppRunning: appController.isRunning(),
+      legacyAppInstalled: appController.isInstalled(),
+      ports: portsProvider.currentPorts())
+  }
+
+  func performHandoff() async throws -> LegacyHandoffReport {
+    guard !appController.isRunning() else {
+      throw LegacyHandoffError.legacyAppRunning
+    }
+    RuntimeLog.emit(.legacyHandoffStarted)
+
+    let detection = detect()
+    if let failure = detection.printFailures.first {
+      throw LegacyHandoffError.detectionFailed(detail: failure)
+    }
+    let plan = LegacyHandoffPlan.make(from: detection)
+
+    // 1) 系统代理先清理：授权交互在最前；失败即中止，一个 job 都不动，
+    //    避免「服务已停、代理仍指向死端口」的断网中间态。
+    let cleanOutcome = try cleanSystemProxy(ports: detection.ports)
+
+    // 2) 按计划执行白名单动作（bootout + 残留 plist disable）。
+    let execution = try await execute(plan.actions)
+
+    // 3) 端口释放门禁：无复用选项的 bind 探测（禁 SO_REUSEPORT——Legacy
+    //    ss-local 带 --reuse-port，复用探测会假成功）。
+    let confirmedFreePorts = try await confirmPortsReleased(detection.ports)
+
+    // 完成标记失败不推翻交接事实（停用已生效、重跑已实弹验证为幂等）：
+    // 记入诊断日志，完成态照常返回。
+    do {
+      try marker.setCompleted(true)
+    } catch {
+      RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error)))
+    }
+    RuntimeLog.emit(.legacyHandoffCompleted)
+
+    return LegacyHandoffReport(
+      bootedOutLabels: execution.bootedOutLabels,
+      killedLabels: execution.killedLabels,
+      disabledLabels: execution.disabledLabels,
+      residue: plan.residue,
+      proxyServicesCleaned: cleanOutcome.cleanedServiceIDs,
+      proxyServicesUntouchedUnknownOwner: cleanOutcome.unknownOwnerServiceIDs,
+      confirmedFreePorts: confirmedFreePorts)
+  }
+
+  // MARK: - 私有步骤
+
+  private func cleanSystemProxy(ports: LegacyListenPorts) throws -> LegacyProxyCleanOutcome {
+    let outcome: LegacyProxyCleanOutcome
+    do {
+      outcome = try proxyCleaner.cleanLegacyOwnedProxy(ports: ports)
+    } catch let error as LegacyHandoffError {
+      throw error
+    } catch {
+      throw LegacyHandoffError.proxyCleanFailed(detail: String(describing: error))
+    }
+    if !outcome.cleanedServiceIDs.isEmpty {
+      RuntimeLog.emit(.legacyHandoffProxyCleaned(serviceCount: outcome.cleanedServiceIDs.count))
+    }
+    return outcome
+  }
+
+  private struct PlanExecution {
+    var bootedOutLabels: [String] = []
+    var killedLabels: [String] = []
+    var disabledLabels: [String] = []
+  }
+
+  /// 逐动作执行：bootout（print 退出码验证，kill 有文档后备）与 disable；
+  /// 任一动作失败即抛错中止后续动作与端口门禁（2.0 不启动）。
+  private func execute(_ actions: [LegacyHandoffAction]) async throws -> PlanExecution {
+    var execution = PlanExecution()
+    for action in actions {
+      switch action {
+      case .bootout(let label):
+        switch await removeJob(label) {
+        case .removed:
+          execution.bootedOutLabels.append(label)
+        case .removedAfterKill:
+          execution.bootedOutLabels.append(label)
+          execution.killedLabels.append(label)
+        case .failure(let detail):
+          RuntimeLog.emit(.legacyHandoffFailed(reason: detail))
+          throw LegacyHandoffError.bootoutFailed(label: label, detail: detail)
+        }
+      case .disable(let label):
+        let outcome = launchctl.disable(label: label)
+        guard outcome.exitCode == 0 else {
+          let detail = Self.describeOutcome(outcome)
+          RuntimeLog.emit(.legacyHandoffFailed(reason: detail))
+          throw LegacyHandoffError.disableFailed(label: label, detail: detail)
+        }
+        execution.disabledLabels.append(label)
+        RuntimeLog.emit(.legacyHandoffLabelDisabled(label: label))
+      }
+    }
+    return execution
+  }
+
+  private static func describeOutcome(_ outcome: LaunchctlOutcome) -> String {
+    outcome.stderr.isEmpty ? "launchctl 退出码 \(outcome.exitCode)" : outcome.stderr
+  }
+
+  private enum RemovalOutcome {
+    case removed
+    case removedAfterKill
+    case failure(detail: String)
+  }
+
+  /// bootout → print 退出码验证（0 已加载 / 113 已移除）；仍加载时用有文档
+  /// 的 `launchctl kill SIGTERM` 后备再验证；绝不升级为进程名匹配。
+  private func removeJob(_ label: String) async -> RemovalOutcome {
+    let outcome = launchctl.bootout(label: label)
+    switch outcome.exitCode {
+    case 0:
+      break
+    case 3, 113:
+      // print 与 bootout 之间自行退出：意图已达成，不视为失败。
+      // 实弹验证（docs/research/legacy-handoff-bootout-live-fire.md）：
+      // 未加载 label 的 bootout 退出码为 3（No such process），print 为 113。
+      return .removed
+    default:
+      return .failure(detail: Self.describeOutcome(outcome))
+    }
+    if await isLabelAbsent(label) {
+      RuntimeLog.emit(.legacyHandoffLabelRemoved(label: label))
+      return .removed
+    }
+    _ = launchctl.kill(label: label, signal: SIGTERM)
+    if await isLabelAbsent(label) {
+      RuntimeLog.emit(.legacyHandoffLabelRemoved(label: label))
+      return .removedAfterKill
+    }
+    return .failure(detail: "bootout 后 launchctl print 仍报告该服务已加载")
+  }
+
+  private func isLabelAbsent(_ label: String) async -> Bool {
+    for attempt in 0..<removalVerifyAttempts {
+      if attempt > 0 {
+        try? await Task.sleep(nanoseconds: removalVerifyIntervalNanoseconds)
+      }
+      if launchctl.serviceState(label: label) == .notLoaded { return true }
+    }
+    return false
+  }
+
+  /// 对三个 Legacy 端口做无复用选项的 bind 探测，限时轮询直到全部空闲；
+  /// 探测地址是 2.0 将绑定自己的回环地址——Legacy 在非回环地址上的监听与
+  /// 2.0 回环绑定不冲突，不构成门禁失败。
+  private func confirmPortsReleased(_ ports: LegacyListenPorts) async throws -> [Int] {
+    let targetPorts = [ports.socksPort, ports.httpPort, ports.pacPort]
+    for attempt in 0..<portPollAttempts {
+      if attempt > 0 {
+        try? await Task.sleep(nanoseconds: portPollIntervalNanoseconds)
+      }
+      if occupiedDescriptions(ports).isEmpty {
+        RuntimeLog.emit(
+          .legacyHandoffPortsConfirmed(
+            portList: targetPorts.map(String.init).joined(separator: "/")))
+        return targetPorts
+      }
+    }
+    let occupied = occupiedDescriptions(ports)
+    RuntimeLog.emit(.legacyHandoffPortsNotReleased(detail: occupied.joined(separator: "、")))
+    throw LegacyHandoffError.portsNotReleased(occupied: occupied)
+  }
+
+  /// 每端口恰好探测一次：占用给「端口（进程名）」，探测自身失败给
+  /// 「端口（无法判定：…）」——无法判定不冒充空闲。
+  private func occupiedDescriptions(_ ports: LegacyListenPorts) -> [String] {
+    [ports.socksPort, ports.httpPort, ports.pacPort].compactMap { port in
+      switch occupancyProbe.occupancy(port: port, bindAddress: "127.0.0.1") {
+      case .free:
+        return nil
+      case .occupied(let occupier):
+        guard let occupier, !occupier.isEmpty else { return String(port) }
+        return "\(port)（\(occupier)）"
+      case .unknown(let detail):
+        return "\(port)（无法判定：\(detail)）"
+      }
+    }
+  }
+}
diff --git a/ShadowsocksX-NG2/Domain/RuntimeLog.swift b/ShadowsocksX-NG2/Domain/RuntimeLog.swift
index dd0e7d79..967bcf32 100644
--- a/ShadowsocksX-NG2/Domain/RuntimeLog.swift
+++ b/ShadowsocksX-NG2/Domain/RuntimeLog.swift
@@ -37,6 +37,16 @@ enum RuntimeLogEvent: CustomStringConvertible, Sendable {
   case endpointProbeFailed(host: String, port: Int, detail: String)
   /// 激活失败或活动目标清除（原因枚举已点名且不含秘密）。
   case activationFailed(reason: String)
+  /// Legacy 交接（issue #37）：label 是产品硬编码白名单常量，端口为本机端点，
+  /// 均非敏感信息。
+  case legacyHandoffStarted
+  case legacyHandoffLabelRemoved(label: String)
+  case legacyHandoffLabelDisabled(label: String)
+  case legacyHandoffProxyCleaned(serviceCount: Int)
+  case legacyHandoffPortsConfirmed(portList: String)
+  case legacyHandoffPortsNotReleased(detail: String)
+  case legacyHandoffFailed(reason: String)
+  case legacyHandoffCompleted
   /// 用户显式触发的脱敏诊断导出已完成（不携带导出路径）。
   case diagnosticsExported
   /// 监听设置持久化读取失败，已回落出厂默认（D8：不静默改端口——事件进
@@ -89,6 +99,22 @@ enum RuntimeLogEvent: CustomStringConvertible, Sendable {
       return "endpoint \(host):\(port) not ready: \(detail)"
     case .activationFailed(let reason):
       return "activation failed: \(reason)"
+    case .legacyHandoffStarted:
+      return "legacy handoff started"
+    case .legacyHandoffLabelRemoved(let label):
+      return "legacy handoff removed launchd job: \(label)"
+    case .legacyHandoffLabelDisabled(let label):
+      return "legacy handoff disabled launchd label: \(label)"
+    case .legacyHandoffProxyCleaned(let serviceCount):
+      return "legacy handoff cleaned legacy-owned system proxy (services=\(serviceCount))"
+    case .legacyHandoffPortsConfirmed(let portList):
+      return "legacy handoff confirmed ports free: \(portList)"
+    case .legacyHandoffPortsNotReleased(let detail):
+      return "legacy handoff ports not released: \(detail)"
+    case .legacyHandoffFailed(let reason):
+      return "legacy handoff failed: \(reason)"
+    case .legacyHandoffCompleted:
+      return "legacy handoff completed"
     case .diagnosticsExported:
       return "diagnostics report exported (redacted)"
     case .listenSettingsUnreadable(let detail):
diff --git a/ShadowsocksX-NG2/Tests/LegacyHandoffFakes.swift b/ShadowsocksX-NG2/Tests/LegacyHandoffFakes.swift
new file mode 100644
index 00000000..7e4e6f0d
--- /dev/null
+++ b/ShadowsocksX-NG2/Tests/LegacyHandoffFakes.swift
@@ -0,0 +1,151 @@
+import Foundation
+import XCTest
+
+@testable import ShadowsocksX_NG2
+
+// MARK: - 交接测试假实现（LegacyHandoffTests / LegacyHandoffViewModelTests 共用）
+
+struct FixedPortsProvider: LegacyListenPortsProviding {
+  func currentPorts() -> LegacyListenPorts { .factory() }
+}
+
+final class FakeHandoffMarker: LegacyHandoffMarkerStoring, @unchecked Sendable {
+  var completed = false
+
+  func isCompleted() -> Bool { completed }
+
+  func setCompleted(_ completed: Bool) { self.completed = completed }
+}
+
+final class FakePlistInspector: LegacyAgentPlistInspecting, @unchecked Sendable {
+  let residues: [LegacyAgentPlistResidue]
+
+  init(residues: [LegacyAgentPlistResidue]) {
+    self.residues = residues
+  }
+
+  func residue(for label: String) -> LegacyAgentPlistResidue {
+    residues.first { $0.label == label }
+      ?? LegacyAgentPlistResidue(
+        label: label, fileExists: false, keepAlive: false, runAtLoad: false)
+  }
+}
+
+final class FakeLegacyAppController: LegacyAppControlling, @unchecked Sendable {
+  var running = false
+  var installed = false
+  private(set) var quitRequested = false
+
+  func isRunning() -> Bool { running }
+
+  func isInstalled() -> Bool { installed }
+
+  func requestGracefulQuit() -> Bool {
+    quitRequested = true
+    running = false
+    return true
+  }
+}
+
+final class FakeOccupancyProbe: PortOccupancyProbing, @unchecked Sendable {
+  var occupiers: [Int: String] = [:]
+  /// 每个端口第 N 次起探测为空闲；nil 表示始终按 occupiers 判定。
+  var occupanciesUntilFree: Int?
+  private(set) var probedPorts: [Int] = []
+
+  func occupancy(port: Int, bindAddress: String) -> PortOccupancy {
+    probedPorts.append(port)
+    if let untilFree = occupanciesUntilFree {
+      let probes = probedPorts.filter { $0 == port }.count
+      if probes >= untilFree { return .free }
+    }
+    guard let occupier = occupiers[port] else { return .free }
+    return .occupied(occupier: occupier)
+  }
+}
+
+final class FakeProxyCleaner: LegacyProxyCleaning, @unchecked Sendable {
+  let outcome: LegacyProxyCleanOutcome?
+  let error: LegacyHandoffError?
+  private(set) var cleanCall: LegacyListenPorts?
+
+  init(outcome: LegacyProxyCleanOutcome? = nil, error: LegacyHandoffError? = nil) {
+    self.outcome = outcome
+    self.error = error
+  }
+
+  func cleanLegacyOwnedProxy(ports: LegacyListenPorts) throws -> LegacyProxyCleanOutcome {
+    cleanCall = ports
+    if let error { throw error }
+    return outcome ?? LegacyProxyCleanOutcome(cleanedServiceIDs: [], unknownOwnerServiceIDs: [])
+  }
+}
+
+/// launchctl 假实现：维护按 label 的加载态机，记录全部调用。
+final class FakeLaunchctl: LaunchctlControlling, @unchecked Sendable {
+  enum LaunchctlCall: Equatable {
+    case state(label: String)
+    case bootout(label: String)
+    case disable(label: String)
+    case kill(label: String, signal: Int32)
+  }
+
+  enum BootoutBehavior {
+    case removes
+    case succeedsButKeepsLoaded
+    case unremovable
+    case alreadyGone
+  }
+
+  var loadedLabels: Set<String> = []
+  var bootoutBehavior: [String: BootoutBehavior] = [:]
+  var disableFailures: [String: LaunchctlOutcome] = [:]
+  var printFailureDetail: [String: String] = [:]
+  private(set) var recordedCalls: [LaunchctlCall] = []
+
+  func serviceState(label: String) -> LaunchctlServiceState {
+    recordedCalls.append(.state(label: label))
+    if let detail = printFailureDetail[label] { return .unknown(detail: detail) }
+    return loadedLabels.contains(label) ? .loaded : .notLoaded
+  }
+
+  func bootout(label: String) -> LaunchctlOutcome {
+    recordedCalls.append(.bootout(label: label))
+    switch bootoutBehavior[label] ?? .removes {
+    case .removes:
+      loadedLabels.remove(label)
+      return LaunchctlOutcome(exitCode: 0, stderr: "")
+    case .succeedsButKeepsLoaded:
+      return LaunchctlOutcome(exitCode: 0, stderr: "")
+    case .unremovable:
+      return LaunchctlOutcome(exitCode: 1, stderr: "launchctl: Operation not permitted")
+    case .alreadyGone:
+      loadedLabels.remove(label)
+      // 实弹验证：bootout 未加载 label 的退出码是 3，不是 print 的 113。
+      return LaunchctlOutcome(exitCode: 3, stderr: "Boot-out failed: 3: No such process")
+    }
+  }
+
+  func disable(label: String) -> LaunchctlOutcome {
+    recordedCalls.append(.disable(label: label))
+    if let failure = disableFailures[label] { return failure }
+    return LaunchctlOutcome(exitCode: 0, stderr: "")
+  }
+
+  func kill(label: String, signal: Int32) -> LaunchctlOutcome {
+    recordedCalls.append(.kill(label: label, signal: signal))
+    if bootoutBehavior[label] == .unremovable { return LaunchctlOutcome(exitCode: 0, stderr: "") }
+    loadedLabels.remove(label)
+    return LaunchctlOutcome(exitCode: 0, stderr: "")
+  }
+}
+
+extension LegacyListenPorts {
+  /// 出厂三端口（D8：1086/1087/1089）。
+  static func factory(
+    socksPort: Int = 1086, httpPort: Int = 1087, pacPort: Int = 1089
+  ) -> LegacyListenPorts {
+    LegacyListenPorts(
+      socksPort: socksPort, httpPort: httpPort, pacPort: pacPort, socksAddress: "127.0.0.1")
+  }
+}
diff --git a/ShadowsocksX-NG2/Tests/LegacyHandoffTests.swift b/ShadowsocksX-NG2/Tests/LegacyHandoffTests.swift
new file mode 100644
index 00000000..76265f61
--- /dev/null
+++ b/ShadowsocksX-NG2/Tests/LegacyHandoffTests.swift
@@ -0,0 +1,362 @@
+import Foundation
+import XCTest
+
+@testable import ShadowsocksX_NG2
+
+/// Legacy 交接主缝（issue #37）：交接计划与执行时序。launchctl/探测/清理用
+/// 假实现观察调用次序与退出码语义，不触碰真实 launchd、系统代理或 Legacy 数据。
+final class LegacyHandoffTests: XCTestCase {
+  // MARK: - 交接计划（纯决策）
+
+  func testPlanBootsLoadedLabelsAndDisablesPlistResidue() {
+    let detection = LegacyHandoffDetection(
+      loadedLabels: [
+        LegacyLaunchAgentLabel.kcptun.rawValue, LegacyLaunchAgentLabel.local.rawValue,
+      ],
+      printFailures: [],
+      plists: [
+        LegacyAgentPlistResidue(
+          label: LegacyLaunchAgentLabel.local.rawValue, fileExists: true,
+          keepAlive: false, runAtLoad: false),
+        LegacyAgentPlistResidue(
+          label: LegacyLaunchAgentLabel.http.rawValue, fileExists: false,
+          keepAlive: false, runAtLoad: false),
+      ],
+      legacyAppRunning: false, legacyAppInstalled: true,
+      ports: .factory())
+
+    let plan = LegacyHandoffPlan.make(from: detection)
+
+    XCTAssertEqual(
+      plan.actions,
+      [
+        .bootout(label: LegacyLaunchAgentLabel.local.rawValue),
+        .disable(label: LegacyLaunchAgentLabel.local.rawValue),
+        .bootout(label: LegacyLaunchAgentLabel.kcptun.rawValue),
+      ])
+    XCTAssertEqual(
+      plan.residue.map(\.label), [LegacyLaunchAgentLabel.local.rawValue])
+  }
+
+  func testPlanHasNoActionsWithoutEvidence() {
+    let detection = LegacyHandoffDetection(
+      loadedLabels: [], printFailures: [],
+      plists: LegacyLaunchAgentLabel.allCases.map { label in
+        LegacyAgentPlistResidue(
+          label: label.rawValue, fileExists: false, keepAlive: false, runAtLoad: false)
+      },
+      legacyAppRunning: false, legacyAppInstalled: false, ports: .factory())
+
+    let plan = LegacyHandoffPlan.make(from: detection)
+
+    XCTAssertTrue(plan.actions.isEmpty)
+    XCTAssertTrue(plan.residue.isEmpty)
+  }
+
+  // MARK: - 服务时序
+
+  func testHappyPathCleansProxyBeforeBootoutThenConfirmsPorts() async throws {
+    let launchctl = FakeLaunchctl()
+    launchctl.loadedLabels = [
+      LegacyLaunchAgentLabel.local.rawValue, LegacyLaunchAgentLabel.http.rawValue,
+    ]
+    let occupancy = FakeOccupancyProbe()
+    let cleaner = FakeProxyCleaner(
+      outcome: LegacyProxyCleanOutcome(
+        cleanedServiceIDs: ["Wi-Fi"], unknownOwnerServiceIDs: []))
+    let service = makeService(launchctl: launchctl, occupancy: occupancy, cleaner: cleaner)
+
+    let report = try await service.performHandoff()
+
+    // 次序：系统代理先清理（授权在前、失败即零影响），再 bootout。
+    XCTAssertNotNil(cleaner.cleanCall)
+    XCTAssertTrue(
+      launchctl.recordedCalls.contains(
+        .bootout(
+          label: LegacyLaunchAgentLabel.local.rawValue)))
+    XCTAssertTrue(
+      launchctl.recordedCalls.contains(
+        .bootout(
+          label: LegacyLaunchAgentLabel.http.rawValue)))
+    XCTAssertEqual(
+      report.bootedOutLabels,
+      [
+        LegacyLaunchAgentLabel.local.rawValue, LegacyLaunchAgentLabel.http.rawValue,
+      ])
+    XCTAssertEqual(report.confirmedFreePorts.sorted(), [1086, 1087, 1089])
+    XCTAssertEqual(report.proxyServicesCleaned, ["Wi-Fi"])
+    XCTAssertTrue(marker.completed)
+    // 交接后验证卸载：每个 bootout 之后紧跟一次 print 验证（只看退出码）。
+    let calls = launchctl.recordedCalls
+    let bootoutIndexes = calls.indices.filter { index in
+      if case .bootout = calls[index] { return true } else { return false }
+    }
+    XCTAssertEqual(bootoutIndexes.count, 2)
+    for index in bootoutIndexes {
+      guard index + 1 < calls.count, case .state = calls[index + 1] else {
+        return XCTFail("bootout 后应立即以 print 退出码验证卸载")
+      }
+    }
+  }
+
+  func testPlistResidueIsDisabledAndReported() async throws {
+    let launchctl = FakeLaunchctl()
+    let plists = [
+      LegacyAgentPlistResidue(
+        label: LegacyLaunchAgentLabel.local.rawValue, fileExists: true,
+        keepAlive: true, runAtLoad: false)
+    ]
+    let service = makeService(
+      launchctl: launchctl,
+      plists: plists,
+      cleaner: FakeProxyCleaner())
+
+    let report = try await service.performHandoff()
+
+    XCTAssertTrue(
+      launchctl.recordedCalls.contains(
+        .disable(
+          label: LegacyLaunchAgentLabel.local.rawValue)))
+    XCTAssertEqual(report.disabledLabels, [LegacyLaunchAgentLabel.local.rawValue])
+    XCTAssertEqual(report.residue.count, 1)
+    XCTAssertTrue(report.residue[0].keepAlive)
+  }
+
+  func testBootoutThatLeavesJobLoadedEscalatesToDocumentedKill() async throws {
+    let launchctl = FakeLaunchctl()
+    let label = LegacyLaunchAgentLabel.local.rawValue
+    launchctl.loadedLabels = [label]
+    launchctl.bootoutBehavior[label] = .succeedsButKeepsLoaded
+    let service = makeService(
+      launchctl: launchctl,
+      cleaner: FakeProxyCleaner())
+
+    let report = try await service.performHandoff()
+
+    XCTAssertTrue(launchctl.recordedCalls.contains(.kill(label: label, signal: SIGTERM)))
+    XCTAssertEqual(report.killedLabels, [label])
+    XCTAssertEqual(report.bootedOutLabels, [label])
+  }
+
+  func testUnremovableJobFailsWithoutPortGate() async {
+    let launchctl = FakeLaunchctl()
+    launchctl.loadedLabels = [LegacyLaunchAgentLabel.local.rawValue]
+    launchctl.bootoutBehavior[LegacyLaunchAgentLabel.local.rawValue] = .unremovable
+    let occupancy = FakeOccupancyProbe()
+    let service = makeService(
+      launchctl: launchctl,
+      occupancy: occupancy,
+      cleaner: FakeProxyCleaner())
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("不可移除的 job 应显式失败")
+    } catch let error as LegacyHandoffError {
+      guard case .bootoutFailed(let label, _) = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+      XCTAssertEqual(label, LegacyLaunchAgentLabel.local.rawValue)
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+    // 端口门禁未执行：失败路径不允许继续启动 2.0。
+    XCTAssertTrue(occupancy.probedPorts.isEmpty)
+    XCTAssertFalse(marker.completed)
+  }
+
+  func testBootoutOfJobThatVanishedBetweenPrintAndBootoutIsNotAnError() async throws {
+    let launchctl = FakeLaunchctl()
+    launchctl.loadedLabels = [LegacyLaunchAgentLabel.local.rawValue]
+    launchctl.bootoutBehavior[LegacyLaunchAgentLabel.local.rawValue] = .alreadyGone
+    let service = makeService(
+      launchctl: launchctl,
+      cleaner: FakeProxyCleaner())
+
+    let report = try await service.performHandoff()
+
+    XCTAssertEqual(report.bootedOutLabels, [LegacyLaunchAgentLabel.local.rawValue])
+  }
+
+  func testPortsStillOccupiedFailsExplicitlyWithoutCompleting() async {
+    let occupancy = FakeOccupancyProbe()
+    occupancy.occupiers = [1086: "ss-local"]
+    let service = makeService(
+      occupancy: occupancy,
+      cleaner: FakeProxyCleaner())
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("端口未释放应显式失败")
+    } catch let error as LegacyHandoffError {
+      guard case .portsNotReleased(let occupied) = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+      XCTAssertEqual(occupied, ["1086（ss-local）"])
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+    XCTAssertFalse(marker.completed)
+  }
+
+  func testPortGatePollsUntilAllThreePortsAreFree() async throws {
+    let occupancy = FakeOccupancyProbe()
+    occupancy.occupiers = [1086: "ss-local", 1089: "ShadowsocksX-NG"]
+    occupancy.occupanciesUntilFree = 2
+    let service = makeService(
+      occupancy: occupancy,
+      cleaner: FakeProxyCleaner())
+
+    let report = try await service.performHandoff()
+
+    XCTAssertEqual(report.confirmedFreePorts.sorted(), [1086, 1087, 1089])
+    XCTAssertEqual(occupancy.probedPorts.filter { $0 == 1086 }.count, 2)
+  }
+
+  func testUnknownOwnerProxyIsReportedUntouched() async throws {
+    let cleaner = FakeProxyCleaner(
+      outcome: LegacyProxyCleanOutcome(
+        cleanedServiceIDs: [], unknownOwnerServiceIDs: ["Wi-Fi", "Ethernet"]))
+    let service = makeService(
+      launchctl: FakeLaunchctl(),
+      cleaner: cleaner)
+
+    let report = try await service.performHandoff()
+
+    XCTAssertEqual(report.proxyServicesUntouchedUnknownOwner, ["Wi-Fi", "Ethernet"])
+    XCTAssertTrue(report.proxyServicesCleaned.isEmpty)
+  }
+
+  func testProxyCleanFailureAbortsBeforeAnyLaunchctlAction() async {
+    let launchctl = FakeLaunchctl()
+    let service = makeService(
+      launchctl: launchctl,
+      cleaner: FakeProxyCleaner(error: LegacyHandoffError.proxyCleanFailed(detail: "授权被拒绝")))
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("系统代理清理失败应中止交接")
+    } catch let error as LegacyHandoffError {
+      guard case .proxyCleanFailed = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+    // 只读识别允许发生；不得有任何 launchd 变更动作。
+    XCTAssertTrue(
+      launchctl.recordedCalls.allSatisfy { call in
+        if case .state = call { return true } else { return false }
+      })
+    XCTAssertFalse(marker.completed)
+  }
+
+  func testRunningLegacyAppRefusesBeforeAnyAction() async {
+    let launchctl = FakeLaunchctl()
+    let app = FakeLegacyAppController()
+    app.running = true
+    let service = makeService(launchctl: launchctl, appController: app)
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("旧版 app 未退出应拒绝交接")
+    } catch let error as LegacyHandoffError {
+      guard case .legacyAppRunning = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+    XCTAssertTrue(launchctl.recordedCalls.isEmpty)
+    XCTAssertFalse(marker.completed)
+  }
+
+  func testUnknownLaunchctlPrintStateAbortsDetection() async {
+    let launchctl = FakeLaunchctl()
+    launchctl.printFailureDetail[LegacyLaunchAgentLabel.http.rawValue] = "launchctl: adhoc"
+    let service = makeService(launchctl: launchctl)
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("launchctl 状态未知应中止")
+    } catch let error as LegacyHandoffError {
+      guard case .detectionFailed = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+    XCTAssertFalse(marker.completed)
+  }
+
+  func testDisableFailureIsFatal() async {
+    let launchctl = FakeLaunchctl()
+    let label = LegacyLaunchAgentLabel.local.rawValue
+    launchctl.disableFailures = [label: LaunchctlOutcome(exitCode: 1, stderr: "denied")]
+    let plists = [
+      LegacyAgentPlistResidue(label: label, fileExists: true, keepAlive: false, runAtLoad: false)
+    ]
+    let service = makeService(
+      launchctl: launchctl,
+      plists: plists,
+      cleaner: FakeProxyCleaner())
+
+    do {
+      _ = try await service.performHandoff()
+      XCTFail("disable 失败应显式失败（残留会在下次登录复活）")
+    } catch let error as LegacyHandoffError {
+      guard case .disableFailed(let failed, _) = error else {
+        return XCTFail("意外的错误：\(error)")
+      }
+      XCTAssertEqual(failed, label)
+    } catch {
+      XCTFail("意外的错误类型：\(error)")
+    }
+  }
+
+  func testCompletionMarkerSurvivesRerunAndDetectReadsState() async throws {
+    let launchctl = FakeLaunchctl()
+    launchctl.loadedLabels = [LegacyLaunchAgentLabel.kcptun.rawValue]
+    let service = makeService(
+      launchctl: launchctl,
+      cleaner: FakeProxyCleaner())
+
+    _ = try await service.performHandoff()
+    XCTAssertTrue(marker.completed)
+
+    // 幂等重跑：一切已移除时同样成功，且再次写入标记。
+    let second = try await service.performHandoff()
+    XCTAssertTrue(second.bootedOutLabels.isEmpty)
+    XCTAssertTrue(marker.completed)
+  }
+
+  // MARK: - 夹具
+
+  private var marker = FakeHandoffMarker()
+
+  override func setUpWithError() throws {
+    try super.setUpWithError()
+    marker = FakeHandoffMarker()
+  }
+
+  private func makeService(
+    launchctl: FakeLaunchctl = FakeLaunchctl(),
+    plists: [LegacyAgentPlistResidue] = [],
+    appController: FakeLegacyAppController = FakeLegacyAppController(),
+    occupancy: FakeOccupancyProbe = FakeOccupancyProbe(),
+    cleaner: FakeProxyCleaner = FakeProxyCleaner()
+  ) -> LegacyHandoffService {
+    let inspector = FakePlistInspector(residues: plists)
+    return LegacyHandoffService(
+      launchctl: launchctl,
+      plistInspector: inspector,
+      appController: appController,
+      portsProvider: FixedPortsProvider(),
+      occupancyProbe: occupancy,
+      proxyCleaner: cleaner,
+      marker: marker,
+      portPollAttempts: 2,
+      portPollIntervalNanoseconds: 1,
+      removalVerifyAttempts: 2,
+      removalVerifyIntervalNanoseconds: 1)
+  }
+}
diff --git a/ShadowsocksX-NG2/Tests/LegacyHandoffViewModelTests.swift b/ShadowsocksX-NG2/Tests/LegacyHandoffViewModelTests.swift
new file mode 100644
index 00000000..6bf929e4
--- /dev/null
+++ b/ShadowsocksX-NG2/Tests/LegacyHandoffViewModelTests.swift
@@ -0,0 +1,142 @@
+import Foundation
+import XCTest
+
+@testable import ShadowsocksX_NG2
+
+/// 交接视图模型（issue #37）：观察编排次序——确认门禁、执行前停 2.0、成功后
+/// 启动 2.0、端口门禁失败不启动；确认按钮只对确有可停用内容且旧版 app 已退
+/// 出的识别结果开放。
+@MainActor
+final class LegacyHandoffViewModelTests: XCTestCase {
+  func testHappyPathStopsProxyHandsOffThenStartsProxy() async {
+    let harness = makeHarness()
+
+    await harness.model.refresh()
+    XCTAssertTrue(harness.model.canConfirm)
+
+    await harness.model.performHandoff()
+
+    XCTAssertEqual(harness.model.phase, .completed)
+    XCTAssertEqual(harness.events, [.stop, .start])
+    XCTAssertTrue(harness.marker.completed)
+    XCTAssertEqual(harness.model.report?.bootedOutLabels, ["com.qiuyuzhou.shadowsocksX-NG.local"])
+    XCTAssertEqual(harness.model.handoffCompleted, true)
+  }
+
+  func testPortsNotReleasedFailsWithoutStartingProxy() async {
+    let occupancy = FakeOccupancyProbe()
+    occupancy.occupiers = [1086: "ss-local"]
+    let harness = makeHarness(occupancy: occupancy)
+
+    await harness.model.refresh()
+    await harness.model.performHandoff()
+
+    guard case .failed(let reason) = harness.model.phase else {
+      return XCTFail("端口未释放应显式失败：\(harness.model.phase)")
+    }
+    XCTAssertTrue(reason.contains("端口未释放"))
+    XCTAssertEqual(harness.events, [.stop])
+    XCTAssertFalse(harness.marker.completed)
+  }
+
+  func testLegacyAppRunningBlocksConfirmation() async {
+    let app = FakeLegacyAppController()
+    app.running = true
+    let harness = makeHarness(appController: app)
+
+    await harness.model.refresh()
+
+    XCTAssertFalse(harness.model.canConfirm)
+    XCTAssertEqual(harness.events, [])
+    await harness.model.performHandoff()
+    XCTAssertEqual(harness.model.phase, .ready)
+    XCTAssertEqual(harness.events, [])
+  }
+
+  func testConfirmationHiddenWhenNothingToStop() async {
+    let launchctl = FakeLaunchctl()
+    let harness = makeHarness(launchctl: launchctl)
+    launchctl.loadedLabels = []
+
+    await harness.model.refresh()
+
+    XCTAssertFalse(harness.model.canConfirm)
+    XCTAssertFalse(harness.model.hasUnknownState)
+  }
+
+  func testUnknownLaunchctlStateBlocksConfirmation() async {
+    let launchctl = FakeLaunchctl()
+    launchctl.printFailureDetail[LegacyLaunchAgentLabel.local.rawValue] = "launchctl: adhoc"
+    let harness = makeHarness(launchctl: launchctl)
+
+    await harness.model.refresh()
+
+    XCTAssertFalse(harness.model.canConfirm)
+    XCTAssertTrue(harness.model.hasUnknownState)
+  }
+
+  func testQuitLegacyAppRequestsQuitAndRedetects() async {
+    let app = FakeLegacyAppController()
+    app.running = true
+    let harness = makeHarness(appController: app)
+
+    await harness.model.refresh()
+    XCTAssertFalse(harness.model.canConfirm)
+
+    harness.model.quitLegacyApp()
+    await Task.yield()
+
+    XCTAssertTrue(app.quitRequested)
+    XCTAssertFalse(app.running)
+  }
+
+  // MARK: - 夹具
+
+  private func makeHarness(
+    launchctl: FakeLaunchctl = FakeLaunchctl(),
+    occupancy: FakeOccupancyProbe = FakeOccupancyProbe(),
+    appController: FakeLegacyAppController = FakeLegacyAppController()
+  ) -> Harness {
+    let marker = FakeHandoffMarker()
+    let service = LegacyHandoffService(
+      launchctl: launchctl,
+      plistInspector: FakePlistInspector(residues: []),
+      appController: appController,
+      portsProvider: FixedPortsProvider(),
+      occupancyProbe: occupancy,
+      proxyCleaner: FakeProxyCleaner(
+        outcome: LegacyProxyCleanOutcome(cleanedServiceIDs: [], unknownOwnerServiceIDs: [])),
+      marker: marker,
+      portPollAttempts: 2,
+      portPollIntervalNanoseconds: 1,
+      removalVerifyAttempts: 2,
+      removalVerifyIntervalNanoseconds: 1)
+    launchctl.loadedLabels = [LegacyLaunchAgentLabel.local.rawValue]
+    let model = LegacyHandoffViewModel(service: service, appController: appController)
+    let harness = Harness(model: model, marker: marker, appController: appController)
+    model.startProxy = { harness.events.append(.start) }
+    model.stopProxy = { harness.events.append(.stop) }
+    return harness
+  }
+
+  private final class Harness {
+    let model: LegacyHandoffViewModel
+    let marker: FakeHandoffMarker
+    let appController: FakeLegacyAppController
+    var events: [ProxyEvent] = []
+
+    init(
+      model: LegacyHandoffViewModel, marker: FakeHandoffMarker,
+      appController: FakeLegacyAppController
+    ) {
+      self.model = model
+      self.marker = marker
+      self.appController = appController
+    }
+  }
+
+  private enum ProxyEvent {
+    case start
+    case stop
+  }
+}
diff --git a/ShadowsocksX-NG2/Tests/LegacySystemProxySignatureTests.swift b/ShadowsocksX-NG2/Tests/LegacySystemProxySignatureTests.swift
new file mode 100644
index 00000000..9a4aa90c
--- /dev/null
+++ b/ShadowsocksX-NG2/Tests/LegacySystemProxySignatureTests.swift
@@ -0,0 +1,185 @@
+import Foundation
+import XCTest
+
+@testable import ShadowsocksX_NG2
+
+/// Legacy 系统代理特征判定与端口来源（issue #37）纯函数面。
+final class LegacySystemProxySignatureTests: XCTestCase {
+  // MARK: - 归属分类（特征值 + 全部启用面匹配）
+
+  func testLegacyPACSignatureClassifiesAsLegacy() {
+    let dictionary: [String: Any] = [
+      "HTTPEnable": 0, "HTTPSEnable": 0, "SOCKSEnable": 0,
+      "ProxyAutoConfigEnable": 1,
+      "ProxyAutoConfigURLString": "http://localhost:1089/proxy.pac",
+      "ExceptionsList": ["localhost"],
+    ]
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .legacy)
+  }
+
+  func testLegacyPACSignatureFollowsConfiguredPort() {
+    let dictionary: [String: Any] = [
+      "ProxyAutoConfigEnable": 1,
+      "ProxyAutoConfigURLString": "http://localhost:2089/proxy.pac",
+    ]
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory(pacPort: 2089)),
+      .legacy)
+  }
+
+  func testLegacySOCKSSignatureClassifiesAsLegacy() {
+    var dictionary = LegacySystemProxySignature.emptyDisabled
+    dictionary["SOCKSEnable"] = 1
+    dictionary["SOCKSProxy"] = "127.0.0.1"
+    dictionary["SOCKSPort"] = 1086
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .legacy)
+  }
+
+  func testLegacyHTTPAndHTTPSSignaturesClassifyAsLegacy() {
+    var dictionary = LegacySystemProxySignature.emptyDisabled
+    dictionary["HTTPEnable"] = 1
+    dictionary["HTTPProxy"] = "127.0.0.1"
+    dictionary["HTTPPort"] = 1087
+    dictionary["HTTPSEnable"] = 1
+    dictionary["HTTPSProxy"] = "127.0.0.1"
+    dictionary["HTTPSPort"] = 1087
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .legacy)
+  }
+
+  func testDisabledFacetsOnlyClassifiesAsNone() {
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(
+        LegacySystemProxySignature.emptyDisabled, ports: .factory()),
+      .none)
+    XCTAssertEqual(LegacySystemProxySignature.classify([:], ports: .factory()), .none)
+  }
+
+  func testForeignPACURLClassifiesAsOther() {
+    let dictionary: [String: Any] = [
+      "ProxyAutoConfigEnable": 1,
+      "ProxyAutoConfigURLString": "https://pac.example.test/proxy.pac",
+    ]
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .other)
+  }
+
+  func testForeignSOCKSEndpointClassifiesAsOther() {
+    var dictionary = LegacySystemProxySignature.emptyDisabled
+    dictionary["SOCKSEnable"] = 1
+    dictionary["SOCKSProxy"] = "127.0.0.1"
+    dictionary["SOCKSPort"] = 64649
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .other)
+  }
+
+  func testMixedLegacyAndForeignFacetsClassifyAsOther() {
+    var dictionary = LegacySystemProxySignature.emptyDisabled
+    dictionary["ProxyAutoConfigEnable"] = 1
+    dictionary["ProxyAutoConfigURLString"] = "http://localhost:1089/proxy.pac"
+    dictionary["SOCKSEnable"] = 1
+    dictionary["SOCKSProxy"] = "127.0.0.1"
+    dictionary["SOCKSPort"] = 64649
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .other)
+  }
+
+  func testVersionedEndpointOfThisProductIsNotLegacySignature() {
+    var dictionary = LegacySystemProxySignature.emptyDisabled
+    dictionary["ProxyAutoConfigEnable"] = 1
+    dictionary["ProxyAutoConfigURLString"] = "http://localhost:1089/v1/proxy.pac?token=abc"
+    XCTAssertEqual(
+      LegacySystemProxySignature.classify(dictionary, ports: .factory()),
+      .other)
+  }
+
+  // MARK: - 清理投影
+
+  func testCleanedDisablesFacetsAndRemovesEndpointsKeepsOtherKeys() {
+    let dictionary: [String: Any] = [
+      "HTTPEnable": 1, "HTTPProxy": "127.0.0.1", "HTTPPort": 1087,
+      "HTTPSEnable": 1, "HTTPSProxy": "127.0.0.1", "HTTPSPort": 1087,
+      "SOCKSEnable": 1, "SOCKSProxy": "127.0.0.1", "SOCKSPort": 1086,
+      "ProxyAutoConfigEnable": 1,
+      "ProxyAutoConfigURLString": "http://localhost:1089/proxy.pac",
+      "ProxyAutoDiscoveryEnable": 1,
+      "ExceptionsList": ["localhost", "example.test"],
+    ]
+
+    let cleaned = LegacySystemProxySignature.cleaned(dictionary)
+
+    XCTAssertEqual(cleaned["HTTPEnable"] as? Int, 0)
+    XCTAssertEqual(cleaned["HTTPSEnable"] as? Int, 0)
+    XCTAssertEqual(cleaned["SOCKSEnable"] as? Int, 0)
+    XCTAssertEqual(cleaned["ProxyAutoConfigEnable"] as? Int, 0)
+    XCTAssertNil(cleaned["HTTPProxy"])
+    XCTAssertNil(cleaned["HTTPPort"])
+    XCTAssertNil(cleaned["HTTPSProxy"])
+    XCTAssertNil(cleaned["HTTPSPort"])
+    XCTAssertNil(cleaned["SOCKSProxy"])
+    XCTAssertNil(cleaned["SOCKSPort"])
+    XCTAssertNil(cleaned["ProxyAutoConfigURLString"])
+    // 非代理端点键保留：绕过列表与自动发现不是 Legacy 数据，不动。
+    XCTAssertEqual(cleaned["ExceptionsList"] as? [String], ["localhost", "example.test"])
+    XCTAssertEqual(cleaned["ProxyAutoDiscoveryEnable"] as? Int, 1)
+  }
+
+  func testCleanedLeavesDisabledFacetEndpointValuesUntouched() {
+    // 已启用面是 Legacy 特征（PAC），但禁用面的端点值可能是手工混入的静止
+    // 数据——清理只处理启用面，禁用面的键值一律保留。
+    let dictionary: [String: Any] = [
+      "ProxyAutoConfigEnable": 1,
+      "ProxyAutoConfigURLString": "http://localhost:1089/proxy.pac",
+      "SOCKSEnable": 0,
+      "SOCKSProxy": "10.0.0.7",
+      "SOCKSPort": 9999,
+    ]
+
+    let cleaned = LegacySystemProxySignature.cleaned(dictionary)
+
+    XCTAssertEqual(cleaned["ProxyAutoConfigEnable"] as? Int, 0)
+    XCTAssertNil(cleaned["ProxyAutoConfigURLString"])
+    XCTAssertEqual(cleaned["SOCKSEnable"] as? Int, 0)
+    XCTAssertEqual(cleaned["SOCKSProxy"] as? String, "10.0.0.7")
+    XCTAssertEqual(cleaned["SOCKSPort"] as? Int, 9999)
+  }
+
+  // MARK: - Legacy 端口来源
+
+  func testPortsProviderReadsLegacyDefaultsWithFactoryFallback() {
+    let defaults = UserDefaults(suiteName: "legacy-handoff-ports-test")!
+    defer { defaults.removePersistentDomain(forName: "legacy-handoff-ports-test") }
+    defaults.removePersistentDomain(forName: "legacy-handoff-ports-test")
+    defaults.set(2086, forKey: "LocalSocks5.ListenPort")
+    defaults.set(2089, forKey: "PacServer.ListenPort")
+    defaults.set("localhost", forKey: "LocalSocks5.ListenAddress")
+
+    let provider = UserDefaultsLegacyListenPortsProvider(
+      defaults: defaults, bundleIdentifier: "legacy-handoff-ports-test")
+
+    XCTAssertEqual(
+      provider.currentPorts(),
+      LegacyListenPorts(socksPort: 2086, httpPort: 1087, pacPort: 2089, socksAddress: "localhost"))
+  }
+
+  func testPortsProviderRejectsInvalidValues() {
+    let defaults = UserDefaults(suiteName: "legacy-handoff-ports-invalid-test")!
+    defaults.removePersistentDomain(forName: "legacy-handoff-ports-invalid-test")
+    defer { defaults.removePersistentDomain(forName: "legacy-handoff-ports-invalid-test") }
+    defaults.set(0, forKey: "LocalSocks5.ListenPort")
+    defaults.set("nonsense", forKey: "PacServer.ListenPort")
+
+    let provider = UserDefaultsLegacyListenPortsProvider(
+      defaults: defaults, bundleIdentifier: "legacy-handoff-ports-invalid-test")
+
+    XCTAssertEqual(provider.currentPorts(), .factory())
+  }
+}
diff --git a/docs/research/legacy-handoff-bootout-live-fire.md b/docs/research/legacy-handoff-bootout-live-fire.md
new file mode 100644
index 00000000..8da088af
--- /dev/null
+++ b/docs/research/legacy-handoff-bootout-live-fire.md
@@ -0,0 +1,34 @@
+# Legacy bootout 实弹验证记录（issue #37 / Further Notes #5 闭环）
+
+- 验证日期：2026-09-21
+- 环境：macOS 27.0（Build 26A428，arm64），uid 501（Aqua gui 域）。研究报告 `wayfinder-issue-17-legacy-handoff.md` §9.2 要求的「受控环境 bootout 演练」在本机以假替身 job 完成：plist 使用与 Legacy 完全相同的 label 与结构（无 RunAtLoad/KeepAlive 的现行形态 + KeepAlive=true 的 2017 前残留形态），可执行体为 `/usr/bin/nc -l 1086`（模拟 ss-local 持有 SOCKS 端口）。Legacy 实际 ss-local/Privoxy 本体未参与（本机无 Legacy 安装）；label、plist 键、启动方式（`launchctl start`）与真实残留一致，launchd 侧行为不受可执行体影响。
+- 基线（验证前）：三个 label `launchctl print gui/501/…` 均退出码 113（未加载）；1086 无监听；`~/Library/LaunchAgents/` 无相关 plist；print-disabled 中已有 `.local`/`.http` 的历史 `=> enabled` 记录（研究报告 §2.1 所述残留）。
+
+## 结果摘要
+
+| # | 场景 | 命令 | 退出码 | 观测 |
+| --- | --- | --- | --- | --- |
+| 1a | 现行形态：job 已加载 + 进程持端口 | bootstrap（exit 0）→ `launchctl start`（exit 0）→ print=0，lsof 见 `nc *:1086 LISTEN`（pid 79755） | — | 无 RunAtLoad 的 plist 注册后不自动启动，须显式 start——与 Legacy 脚本行为一致 |
+| 1b | **bootout 运行中的 job** | `launchctl bootout gui/501/com.qiuyuzhou.shadowsocksX-NG.local` | **0**（wall ≈20ms） | +100ms 内：print→**113**、lsof 无监听、nc 进程消失。SIGTERM→等退出的等待期短到不可观测 |
+| 2a | KeepAlive 残留形态被外部杀死 | plist 带 `KeepAlive: true`，bootstrap 后 `kill -9` 持有进程 | — | ≤2s 内 launchd 重启新进程（pid 80094→80108），端口继续被持有——证实活跃残留会自我复活 |
+| 2b | **bootout KeepAlive job** | 同 1b | **0** | 进程退出、端口释放、print→113，连续 5s 无重启（KeepAlive 重启依据随 job 定义一并移除） |
+| 3a | **bootout 未加载的 label** | 同 1b | **3**（stderr `Boot-out failed: 3: No such process`） | **不是 print 的 113**——退出码语义按子命令而异，产品代码把 0/3 都按「已移除」处理 |
+| 3b | job 已加载但 plist 文件已删（错位形态） | bootstrap+start 后 `rm plist` 再 bootout | **0** | 按 service target bootout 不需要 plist 存在；print→113、端口释放 |
+| 3d | `launchctl kill 15` 后备 | `launchctl kill 15 gui/501/<label>` | **0** | 旧进程收到 SIGTERM 退出，但 **job 定义仍在（print=0）**，KeepAlive 形态下进程立即被重启——kill 只是终止不是移除，验证后仍须 bootout |
+| 3e | disable / enable 语义 | `launchctl disable gui/501/<dummy>` | **0**（幂等） | print-disabled 立即出现 `<dummy> => disabled`；disabled 状态下 bootstrap 该 label 失败（`5: Input/output error`）——disable 确实阻止加载且跨启动持久；`enable` 后记录变为 `=> enabled`（记录保留，状态翻转） |
+
+## 对产品实现的直接修正
+
+1. `LegacyHandoffService.removeJob` 把 bootout 退出码 **0 与 3** 都视为「已移除」（3 = print 与 bootout 之间自行退出的竞态，或检测后未再加载）。测试假实现同步改为 3。
+2. kill 后备的验证判据维持 print 退出码（kill 不改变注册态，print=0 ⇒ kill 未达成移除，继续升级为失败呈现）。
+
+## 清理与残留声明
+
+- 验证后：三个 label print 均 113；1086 空闲；`~/Library/LaunchAgents/` 无相关 plist；`/tmp` 临时 plist 已删。
+- print-disabled 中 `.local`/`.http` 的历史 `=> enabled` 记录与验证前一致（bootstrap/bootout 不写 override 记录）。
+- 唯一新痕迹：dummy label `com.qiuyuzhou.shadowsocksx-ng2.live-test-dummy` 在 print-disabled 留下一条 `=> enabled` 记录（enabled 即默认态，无行为影响；launchctl 无删除单条记录的接口）。
+
+## 遗留验证余项（不阻塞本票）
+
+- macOS 15 与 27 的 print-disabled 呈现细节、`statusForLegacyURL:` 对第三方 plist 的返回语义（研究报告 §9.1）。
+- 真实 Legacy ss-local（`--reuse-port`）的端口释放时序：本验证用 nc（无复用选项）替身；bind 探测「无 SO_REUSEPORT ⇒ 真占用」的语义已由研究报告 §2.3 论证，产品探测不设置任何复用选项。