fix: make managed SSH sessions fast and resilient

Managed SSH project selection repeatedly activated the remote Host and could leave idle ACP bindings rejected as stale-controller after a controller generation change. Host environment updates also coupled project state to component installation evidence and presented a crowded control surface. Project selection is now local-only, one Host connection serves compatible project and conversation callers, idle bindings are safely replaced only after proven controller takeover, and active prompts keep exact resume/replay. Remote environment setup now uses explicit signed compound package preparation with bounded transfer, rollback, recovery, and clearer settings. Managed Hosts must be updated to separately distributed Agent 0.11.6 before the daemon-side controller recovery fix takes effect. Desktop packages do not embed the Agent or remote Runtime, and existing project data is preserved. Release note: 托管 SSH 项目切换不再重复连接，同一 Host 可顺畅承载多个项目和对话；同时修复重连后的 stale-controller，并优化远程环境安装、更新与状态布局。
2026-08-29 10:58:19 +08:00
parent eb947213c8
commit 459cc21e3d
117 changed files with 19876 additions and 9664 deletions
@@ -0,0 +1,825 @@
+import { randomUUID } from 'node:crypto'
+import { dirname } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import type {
+  RemoteEnvironmentPreparationMethod,
+  RemoteEnvironmentUpdateProgress
+} from '../../shared/ssh-host-contracts'
+import type { StagedSftp } from '../ssh/bounded-sftp'
+import { verifyAgentInstallationId } from '../ssh/ssh-agent-command'
+import type {
+  SshConnectionLease,
+  SshConnectionPool,
+  SshRemotePackageBootstrapLease
+} from '../ssh/ssh-connection-pool'
+import type { SshConnectionTarget } from '../ssh/ssh-host-store'
+import {
+  assertSshLeaseMatchesTarget,
+  assertValidSshConnectionTarget
+} from '../ssh/ssh-connection-target'
+import {
+  SshRemotePackageCommitIndeterminateError,
+  type SshRemotePackageBootstrapPrepareResult,
+  type SshRemotePackageBootstrapProgress,
+  type SshRemotePackageCandidate,
+  type SshRemotePackageIdentity
+} from '../ssh/ssh-remote-package-bootstrap'
+import type {
+  AgentInstallationManager,
+  AgentInstallationTargetResolver
+} from './agent-installation-manager'
+import type {
+  AgentPackageArchiveLease,
+  AgentPackageManager,
+  VerifiedRemoteAgentInstallCandidate
+} from './agent-package-manager'
+import {
+  restoreRemoteEnvironmentMetadata,
+  snapshotRemoteEnvironmentMetadata,
+  type RemoteEnvironmentMetadataSnapshot
+} from './remote-environment-metadata'
+import {
+  mapAgentInstallationPhase,
+  mapRuntimeInstallationPhase
+} from './remote-environment-progress'
+import type {
+  RemoteEnvironmentOperationStore
+} from './remote-environment-operation-store'
+import type {
+  RemoteEnvironmentPreparer as Preparer,
+  RemoteEnvironmentUpdateProgressObserver
+} from './remote-environment-update-service'
+import type {
+  RemoteRuntimeInstallationManager
+} from './remote-runtime-installation-manager'
+import {
+  remoteHostRecoveryIdentityKey
+} from './remote-host-target-identity'
+
+const MAXIMUM_PACKAGE_BYTES = 512 * 1024 * 1024
+const MAXIMUM_METADATA_BYTES = 1024 * 1024
+
+export type RemoteEnvironmentPreparerOptions = {
+  resolver: AgentInstallationTargetResolver
+  sshPool: Pick<
+    SshConnectionPool,
+    'acquire' | 'acquireRemotePackageBootstrap'
+  >
+  agentPackageManager: Pick<
+    AgentPackageManager,
+    | 'getRemoteInstallCandidate'
+    | 'acquireInstallArchive'
+    | 'acquireGoodBuddyInstallArchive'
+  >
+  agentInstallationManager: Pick<
+    AgentInstallationManager,
+    'activatePublished'
+  >
+  runtimeInstallationManager: Pick<
+    RemoteRuntimeInstallationManager,
+    'activatePublished'
+  >
+  operationStore: Pick<
+    RemoteEnvironmentOperationStore,
+    'load' | 'save' | 'remove'
+  >
+}
+
+/**
+ * Prepares one signed compound environment. The selected method controls only
+ * how the archive reaches the Host; both paths share prepare, commit,
+ * activation, rollback, health checks, and cleanup.
+ */
+export class RemoteEnvironmentPreparer implements Preparer {
+  readonly #resolver: AgentInstallationTargetResolver
+  readonly #sshPool: RemoteEnvironmentPreparerOptions['sshPool']
+  readonly #agentPackageManager:
+    RemoteEnvironmentPreparerOptions['agentPackageManager']
+  readonly #agentInstallationManager:
+    RemoteEnvironmentPreparerOptions['agentInstallationManager']
+  readonly #runtimeInstallationManager:
+    RemoteEnvironmentPreparerOptions['runtimeInstallationManager']
+  readonly #operationStore:
+    RemoteEnvironmentPreparerOptions['operationStore']
+
+  constructor(options: RemoteEnvironmentPreparerOptions) {
+    this.#resolver = options.resolver
+    this.#sshPool = options.sshPool
+    this.#agentPackageManager = options.agentPackageManager
+    this.#agentInstallationManager =
+      options.agentInstallationManager
+    this.#runtimeInstallationManager =
+      options.runtimeInstallationManager
+    this.#operationStore = options.operationStore
+  }
+
+  async prepare(
+    hostId: string,
+    requestedMethod: RemoteEnvironmentPreparationMethod,
+    observer: RemoteEnvironmentUpdateProgressObserver | undefined,
+    signal: AbortSignal
+  ): Promise<void> {
+    const emit = (
+      method: RemoteEnvironmentPreparationMethod,
+      phase: RemoteEnvironmentUpdateProgress['phase']
+    ): void => {
+      try {
+        observer?.({ hostId, method, phase })
+      } catch {
+        // Progress observers cannot alter installation state.
+      }
+    }
+
+    signal.throwIfAborted()
+    emit(requestedMethod, 'probing')
+    const target = await this.#resolver.resolve(hostId)
+    signal.throwIfAborted()
+    assertValidSshConnectionTarget(hostId, target)
+    await this.#reconcilePendingOperation(
+      hostId,
+      target,
+      emit,
+      signal
+    )
+
+    let probeLease: SshConnectionLease | undefined
+    let bootstrapLease:
+      | SshRemotePackageBootstrapLease
+      | undefined
+    let archiveLease: AgentPackageArchiveLease | undefined
+    let metadataSftp: StagedSftp | undefined
+    let metadataSnapshots:
+      | readonly RemoteEnvironmentMetadataSnapshot[]
+      | undefined
+    let operationId: string | undefined
+    let operationCleaned = false
+    let pendingOperationSaved = false
+    let committedIdentity: SshRemotePackageIdentity | undefined
+    try {
+      probeLease = await this.#sshPool.acquire(target, signal)
+      assertLeaseMatchesTarget(probeLease, target)
+      const probe = await probeLease.runAgentBootstrapProbe(signal)
+      signal.throwIfAborted()
+      assertLeaseMatchesTarget(probeLease, target)
+      if (!probe.ready) {
+        throw new Error(
+          `远端系统不能运行 GoodBuddy Agent：${probe.reason}`
+        )
+      }
+
+      let candidate: VerifiedRemoteAgentInstallCandidate
+      let method:
+        | 'remote-download'
+        | 'goodbuddy-transfer'
+        | undefined
+      if (requestedMethod === 'goodbuddy-transfer') {
+        archiveLease =
+          await this.#acquireGoodBuddyArchive(
+            probe.architecture,
+            emit,
+            signal
+          )
+        candidate = archiveLease.candidate
+        method = 'goodbuddy-transfer'
+      } else {
+        try {
+          candidate =
+            await this.#agentPackageManager.getRemoteInstallCandidate(
+              probe.architecture,
+              { signal }
+            )
+        } catch (error) {
+          if (requestedMethod === 'remote-download') {
+            throw error
+          }
+          archiveLease =
+            await this.#acquireGoodBuddyArchive(
+              probe.architecture,
+              emit,
+              signal
+            )
+          candidate = archiveLease.candidate
+          method = 'goodbuddy-transfer'
+        }
+      }
+      signal.throwIfAborted()
+      assertCandidate(candidate, probe.architecture)
+      await assertTargetCurrent(this.#resolver, target, signal)
+
+      operationId = randomUUID()
+      const remoteCandidate: SshRemotePackageCandidate = {
+        operationId,
+        urls: candidate.urls,
+        size: candidate.size,
+        sha256: candidate.sha256
+      }
+      bootstrapLease =
+        await this.#sshPool.acquireRemotePackageBootstrap(
+          target,
+          signal
+        )
+      assertLeaseMatchesTarget(bootstrapLease, target)
+      assertSameLeaseIdentity(probeLease, bootstrapLease)
+
+      if (!method) {
+        method = await resolvePreparationMethod(
+          requestedMethod,
+          bootstrapLease,
+          remoteCandidate,
+          signal
+        )
+      }
+      if (
+        method === 'goodbuddy-transfer' &&
+        !archiveLease
+      ) {
+        archiveLease =
+          await this.#agentPackageManager.acquireInstallArchive(
+            candidate.architecture,
+            candidate,
+            {
+              signal,
+              onProgress: (progress) => {
+                emit(
+                  method!,
+                  progress.phase === 'downloading'
+                    ? 'downloading'
+                    : progress.phase === 'catalog'
+                      ? 'probing'
+                      : 'verifying'
+                )
+              }
+            }
+          )
+      }
+      emit(method, 'probing')
+
+      // Persist recovery identity before either preparation path may create
+      // remote staging. A Main crash must never leave an untracked operation.
+      await this.#operationStore.save({
+        version: 1,
+        hostId,
+        targetIdentity: remoteHostRecoveryIdentityKey(target),
+        operationId,
+        size: remoteCandidate.size,
+        sha256: remoteCandidate.sha256,
+        urls: [...remoteCandidate.urls]
+      })
+      pendingOperationSaved = true
+
+      const prepared =
+        method === 'remote-download'
+          ? await bootstrapLease.prepare(remoteCandidate, {
+              signal,
+              onProgress: (progress) => {
+                emit(method, mapBootstrapPhase(progress))
+              }
+            })
+          : await this.#prepareUploadedArchive({
+              probeLease,
+              bootstrapLease,
+              archive: archiveLease!,
+              remoteCandidate,
+              method,
+              emit,
+              signal
+            })
+      assertPrepared(prepared, operationId)
+      assertPackageIdentity(prepared.identity, candidate)
+
+      // Snapshot the complete environment before commit so an Agent success
+      // followed by a Runtime failure cannot expose a partially adopted pair.
+      metadataSftp = await probeLease.openStagedSftp(
+        probe.canonicalHomeDirectory,
+        {
+          maximumFileBytes: MAXIMUM_METADATA_BYTES,
+          maximumTotalBytes: MAXIMUM_METADATA_BYTES * 24,
+          maximumOperations: 128
+        },
+        signal
+      )
+      metadataSnapshots =
+        await snapshotRemoteEnvironmentMetadata(
+          metadataSftp,
+          probe.uid,
+          signal
+        )
+
+      // Keep the full target re-resolution immediately adjacent to commit.
+      await assertTargetCurrent(this.#resolver, target, signal)
+      assertLeaseMatchesTarget(bootstrapLease, target)
+      signal.throwIfAborted()
+
+      const committed = await bootstrapLease.commit(
+        remoteCandidate,
+        {
+          signal,
+          onProgress: (progress) => {
+            emit(method, mapBootstrapPhase(progress))
+          }
+        }
+      )
+      signal.throwIfAborted()
+      if (!committed.committed) {
+        if (
+          committed.reason ===
+          'installer-rollback-incomplete'
+        ) {
+          throw new SshRemotePackageCommitIndeterminateError(
+            '远端环境发布失败且回滚结果不完整，请重新检查 Host 状态'
+          )
+        }
+        throw new Error(
+          `远端安装提交失败：${committed.reason}`
+        )
+      }
+      if (
+        committed.operationId !== operationId ||
+        !isDeepStrictEqual(
+          committed.identity,
+          prepared.identity
+        )
+      ) {
+        throw new Error('远端安装提交身份与准备身份不匹配')
+      }
+      assertPackageIdentity(committed.identity, candidate)
+      committedIdentity = committed.identity
+
+      await assertTargetCurrent(this.#resolver, target, signal)
+      const activeAgent =
+        await this.#agentInstallationManager.activatePublished(
+        hostId,
+        committed.identity.agent,
+        {
+          signal,
+          onProgress: (phase) => {
+            const mapped = mapAgentInstallationPhase(phase)
+            if (mapped) {
+              emit(method, mapped)
+            }
+          }
+        }
+      )
+      signal.throwIfAborted()
+      await assertTargetCurrent(this.#resolver, target, signal)
+
+      await this.#runtimeInstallationManager.activatePublished(
+        hostId,
+        committed.identity.runtime,
+        {
+          agentInstallationId: activeAgent.installationId,
+          signal,
+          onProgress: (phase) => {
+            const mapped = mapRuntimeInstallationPhase(phase)
+            if (mapped) {
+              emit(method, mapped)
+            }
+          }
+        }
+      )
+      signal.throwIfAborted()
+      await assertTargetCurrent(this.#resolver, target, signal)
+
+      const cleanup = await bootstrapLease.cleanup(operationId, {
+        signal
+      })
+      if (!cleanup.cleaned) {
+        throw new Error(
+          `远程环境已安装，但暂存文件清理失败：${cleanup.reason}`
+        )
+      }
+      operationCleaned = true
+      await this.#operationStore.remove(hostId)
+    } catch (error) {
+      let rollbackError: unknown
+      if (
+        committedIdentity &&
+        metadataSftp &&
+        metadataSnapshots
+      ) {
+        await stopCandidateBestEffort(
+          probeLease,
+          committedIdentity.agent.installationId
+        )
+        try {
+          await restoreRemoteEnvironmentMetadata(
+            metadataSftp,
+            metadataSnapshots
+          )
+        } catch (reason) {
+          rollbackError = reason
+        }
+      }
+      if (
+        operationId &&
+        bootstrapLease &&
+        !operationCleaned &&
+        !(error instanceof SshRemotePackageCommitIndeterminateError)
+      ) {
+        operationCleaned = await cleanupBestEffort(
+          bootstrapLease,
+          operationId
+        )
+        if (operationCleaned && pendingOperationSaved) {
+          await this.#operationStore.remove(hostId)
+        }
+      }
+      if (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          '远程运行环境准备失败，且原有环境元数据未能完整恢复',
+          { cause: error }
+        )
+      }
+      throw error
+    } finally {
+      metadataSftp?.close()
+      archiveLease?.release()
+      bootstrapLease?.release()
+      probeLease?.release()
+    }
+  }
+
+  async #prepareUploadedArchive(options: {
+    probeLease: SshConnectionLease
+    bootstrapLease: SshRemotePackageBootstrapLease
+    archive: AgentPackageArchiveLease
+    remoteCandidate: SshRemotePackageCandidate
+    method: 'goodbuddy-transfer'
+    emit: (
+      method: RemoteEnvironmentPreparationMethod,
+      phase: RemoteEnvironmentUpdateProgress['phase']
+    ) => void
+    signal: AbortSignal
+  }): Promise<SshRemotePackageBootstrapPrepareResult> {
+    const {
+      probeLease,
+      bootstrapLease,
+      archive,
+      remoteCandidate,
+      method,
+      emit,
+      signal
+    } = options
+    signal.throwIfAborted()
+
+    const staging = await bootstrapLease.createUploadStaging(
+      remoteCandidate,
+      { signal }
+    )
+    if (!staging.created) {
+      throw new Error(
+        staging.unavailable
+          ? `GoodBuddy 传输暂存不可用：${staging.reason}`
+          : `GoodBuddy 传输暂存失败：${staging.reason}`
+      )
+    }
+    if (staging.operationId !== remoteCandidate.operationId) {
+      throw new Error('GoodBuddy 传输暂存操作身份不匹配')
+    }
+    const operationRoot = dirname(staging.archivePath)
+    if (
+      staging.archivePath !==
+        `${operationRoot}/package.gbagent` ||
+      staging.bootstrapNodePath !==
+        `${operationRoot}/bootstrap/agent/node`
+    ) {
+      throw new Error('GoodBuddy 传输暂存路径无效')
+    }
+
+    const sftp = await probeLease.openStagedSftp(
+      operationRoot,
+      {
+        maximumFileBytes: MAXIMUM_PACKAGE_BYTES,
+        maximumTotalBytes:
+          archive.size + archive.nodeSize,
+        maximumOperations: 16
+      },
+      signal
+    )
+    try {
+      emit(method, 'downloading')
+      await sftp.uploadFile(
+        'package.gbagent',
+        archive.path,
+        {
+          size: archive.size,
+          sha256: archive.sha256
+        },
+        signal
+      )
+      await sftp.uploadFile(
+        'bootstrap/agent/node',
+        archive.nodePath,
+        {
+          size: archive.nodeSize,
+          sha256: archive.nodeSha256
+        },
+        signal
+      )
+      await sftp.setExecutable(
+        'bootstrap/agent/node',
+        signal
+      )
+    } finally {
+      sftp.close()
+    }
+
+    return bootstrapLease.prepareUploaded(remoteCandidate, {
+      signal,
+      onProgress: (progress) => {
+        emit(method, mapBootstrapPhase(progress))
+      }
+    })
+  }
+
+  #acquireGoodBuddyArchive(
+    architecture: 'x64' | 'arm64',
+    emit: (
+      method: RemoteEnvironmentPreparationMethod,
+      phase: RemoteEnvironmentUpdateProgress['phase']
+    ) => void,
+    signal: AbortSignal
+  ): Promise<AgentPackageArchiveLease> {
+    return this.#agentPackageManager.acquireGoodBuddyInstallArchive(
+      architecture,
+      {
+        signal,
+        onProgress: (progress) => {
+          emit(
+            'goodbuddy-transfer',
+            progress.phase === 'downloading'
+              ? 'downloading'
+              : progress.phase === 'catalog'
+                ? 'probing'
+                : 'verifying'
+          )
+        }
+      }
+    )
+  }
+
+  async #reconcilePendingOperation(
+    hostId: string,
+    target: SshConnectionTarget,
+    emit: (
+      method: RemoteEnvironmentPreparationMethod,
+      phase: RemoteEnvironmentUpdateProgress['phase']
+    ) => void,
+    signal: AbortSignal
+  ): Promise<void> {
+    const pending = await this.#operationStore.load(hostId)
+    if (!pending) {
+      return
+    }
+    if (
+      pending.targetIdentity !==
+      remoteHostRecoveryIdentityKey(target)
+    ) {
+      throw new SshRemotePackageCommitIndeterminateError(
+        'SSH Host 连接目标已变化，无法确认上一次远程环境提交；请恢复原 Host 连接后重试，或删除此 Host 以明确放弃恢复'
+      )
+    }
+    emit('auto', 'applying')
+    const candidate: SshRemotePackageCandidate = {
+      operationId: pending.operationId,
+      size: pending.size,
+      sha256: pending.sha256,
+      urls: pending.urls
+    }
+    const lease =
+      await this.#sshPool.acquireRemotePackageBootstrap(
+        target,
+        signal
+      )
+    try {
+      assertLeaseMatchesTarget(lease, target)
+      const status = await lease.commitStatus(candidate, {
+        signal
+      })
+      if (
+        !status.committed &&
+        status.reason === 'installer-rollback-incomplete'
+      ) {
+        throw new SshRemotePackageCommitIndeterminateError(
+          '上一次远程环境发布失败且回滚结果不完整，请检查 Host 状态'
+        )
+      }
+      const cleanup = await lease.cleanup(
+        pending.operationId,
+        { signal }
+      )
+      if (
+        !cleanup.cleaned &&
+        cleanup.reason !== 'operation-unavailable'
+      ) {
+        throw new Error(
+          `上一次远程环境暂存清理失败：${cleanup.reason}`
+        )
+      }
+      await this.#operationStore.remove(hostId)
+    } catch (error) {
+      if (
+        error instanceof
+        SshRemotePackageCommitIndeterminateError
+      ) {
+        throw error
+      }
+      throw new SshRemotePackageCommitIndeterminateError(
+        '上一次远程环境提交结果仍不确定，请稍后重试'
+      )
+    } finally {
+      lease.release()
+    }
+  }
+}
+
+async function resolvePreparationMethod(
+  requested: RemoteEnvironmentPreparationMethod,
+  lease: SshRemotePackageBootstrapLease,
+  candidate: SshRemotePackageCandidate,
+  signal: AbortSignal
+): Promise<'remote-download' | 'goodbuddy-transfer'> {
+  if (requested !== 'auto') {
+    return requested
+  }
+  const availability = await lease.probe(candidate, { signal })
+  return availability.available
+    ? 'remote-download'
+    : 'goodbuddy-transfer'
+}
+
+function assertPrepared(
+  prepared: SshRemotePackageBootstrapPrepareResult,
+  operationId: string
+): asserts prepared is Extract<
+  SshRemotePackageBootstrapPrepareResult,
+  { prepared: true }
+> {
+  if (!prepared.prepared) {
+    throw new Error(
+      prepared.unavailable
+        ? `远端环境准备不可用：${prepared.reason}`
+        : `远端环境准备失败：${prepared.reason}`
+    )
+  }
+  if (prepared.operationId !== operationId) {
+    throw new Error('远端环境准备操作身份不匹配')
+  }
+}
+
+async function cleanupBestEffort(
+  lease: SshRemotePackageBootstrapLease,
+  operationId: string
+): Promise<boolean> {
+  try {
+    const result = await lease.cleanup(operationId)
+    return (
+      result.cleaned ||
+      result.reason === 'operation-unavailable'
+    )
+  } catch {
+    // Preserve the original deterministic preparation failure.
+    return false
+  }
+}
+
+async function stopCandidateBestEffort(
+  lease: SshConnectionLease | undefined,
+  installationId: string
+): Promise<void> {
+  if (!lease?.isUsable()) {
+    return
+  }
+  try {
+    await lease.runAgentLifecycleAction(
+      verifyAgentInstallationId(installationId),
+      'stop'
+    )
+  } catch {
+    // Metadata rollback remains the authoritative recovery action.
+  }
+}
+
+async function assertTargetCurrent(
+  resolver: AgentInstallationTargetResolver,
+  expected: SshConnectionTarget,
+  signal: AbortSignal
+): Promise<void> {
+  signal.throwIfAborted()
+  const current = await resolver.resolve(expected.host.id)
+  signal.throwIfAborted()
+  assertValidSshConnectionTarget(expected.host.id, current)
+  if (!isDeepStrictEqual(current, expected)) {
+    throw new Error(
+      'SSH 主机身份在远端环境安装期间发生变化'
+    )
+  }
+}
+
+function assertLeaseMatchesTarget(
+  lease: Pick<SshConnectionLease, 'identity'>,
+  target: SshConnectionTarget
+): void {
+  assertSshLeaseMatchesTarget(
+    lease,
+    target,
+    'SSH 远端安装连接身份不匹配'
+  )
+  if (
+    !/^[a-f0-9]{64}$/u.test(
+      lease.identity.authenticationIdentity
+    )
+  ) {
+    throw new Error('SSH 远端安装连接身份不匹配')
+  }
+}
+
+function assertSameLeaseIdentity(
+  probeLease: Pick<SshConnectionLease, 'identity'>,
+  bootstrapLease: Pick<
+    SshRemotePackageBootstrapLease,
+    'identity'
+  >
+): void {
+  if (
+    !isDeepStrictEqual(
+      probeLease.identity,
+      bootstrapLease.identity
+    )
+  ) {
+    throw new Error('SSH 远端安装认证身份发生变化')
+  }
+}
+
+function assertCandidate(
+  candidate: VerifiedRemoteAgentInstallCandidate,
+  architecture: 'x64' | 'arm64'
+): void {
+  if (
+    candidate.platform !== 'linux' ||
+    candidate.architecture !== architecture
+  ) {
+    throw new Error('签名 Agent 安装候选与 Host 架构不匹配')
+  }
+}
+
+function assertPackageIdentity(
+  identity: SshRemotePackageIdentity,
+  candidate: VerifiedRemoteAgentInstallCandidate
+): void {
+  if (
+    identity.archiveSha256 !== candidate.sha256 ||
+    identity.agent.agentVersion !== candidate.version ||
+    identity.agent.platform !== candidate.platform ||
+    identity.agent.architecture !== candidate.architecture ||
+    !isDeepStrictEqual(
+      identity.agent.protocol,
+      candidate.agentProtocol
+    ) ||
+    identity.runtime.runtimeId !==
+      candidate.remoteRuntime.runtimeId ||
+    identity.runtime.runtimeVersion !==
+      candidate.remoteRuntime.version ||
+    identity.runtime.bundleDigest !==
+      candidate.remoteRuntime.bundleDigest ||
+    identity.runtime.platform !== candidate.platform ||
+    identity.runtime.architecture !==
+      candidate.architecture ||
+    !isDeepStrictEqual(
+      identity.runtime.protocol,
+      candidate.remoteRuntime.protocol
+    )
+  ) {
+    throw new Error('远端准备的安装身份与签名候选不匹配')
+  }
+}
+
+function mapBootstrapPhase(
+  progress: SshRemotePackageBootstrapProgress
+): RemoteEnvironmentUpdateProgress['phase'] {
+  switch (progress.phase) {
+    case 'checking':
+      return 'probing'
+    case 'downloading':
+      return 'downloading'
+    case 'verifying':
+    case 'validating':
+    case 'hashing-archive':
+    case 'verifying-zip':
+    case 'verifying-payload':
+    case 'validating-prepared-state':
+    case 'revalidating-archive':
+      return 'verifying'
+    case 'extracting':
+    case 'preparing':
+    case 'prepared':
+    case 'committing':
+    case 'committed':
+    case 'persisting-prepared-state':
+    case 'extracting-payload':
+    case 'publishing-content':
+    case 'cleaning':
+      return 'applying'
+  }
+}