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，并优化远程环境安装、更新与状态布局。

src/shared/agent-package-contracts.test.ts

@@ -62,6 +62,17 @@ describe('Agent package contracts', () => {
     ).toThrow()
   })
 
+  it('rejects unknown catalog entry metadata', () => {
+    expect(() =>
+      agentPackageCatalogEntrySchema.parse({
+        ...catalogEntry(),
+        bootstrapCapability: {
+          version: 1
+        }
+      })
+    ).toThrow()
+  })
+
   it('requires one local inventory entry per architecture', () => {
     const entry = {
       platform: 'linux',

src/shared/assistant-contracts.test.ts

@@ -9,8 +9,6 @@ import {
   persistedProjectExecutionSpaceSchema,
   projectCreateSchema,
   projectExecutionSpaceSchema,
-  projectRuntimeValidationSchema,
-  sshExecutionValidationSchema,
   projectUpdateSchema
 } from './assistant-contracts'
 
@@ -132,120 +130,26 @@ describe('project execution space contracts', () => {
     ).toBe(false)
   })
 
-  it('keeps SSH and Runtime validation identities separate and strict', () => {
-    const validatedAt = '2026-08-21T00:00:00.000Z'
-    const validation = {
-      hostRevision: 2,
-      hostKeyGeneration: 3,
-      remoteUsername: 'builder',
-      workspaceIdentity: 'workspace-identity',
-      agentProtocolMajor: 1,
-      agentInstallationIdAtValidation: 'agent-installation',
-      agentBinaryDigestAtValidation: `sha256:${'a'.repeat(64)}`,
-      agentVersionAtValidation: '0.11.0',
-      agentArchitectureAtValidation: 'x64',
-      validatedAt
-    }
-    const runtimeValidation = {
-      runtimeSelectionKey: 'opencode:profile',
-      runtimeBundleDigest: `sha256:${'b'.repeat(64)}`,
-      runtimeAdapterDigest: `sha256:${'c'.repeat(64)}`,
-      agentInstallationIdAtValidation: 'agent-installation',
-      validatedAt,
-      workMode: 'execute'
-    }
-    expect(
-      sshExecutionValidationSchema.safeParse(validation).success
-    ).toBe(true)
-    expect(
-      projectRuntimeValidationSchema.safeParse(runtimeValidation)
-        .success
-    ).toBe(true)
+  it('persists only the SSH Host and remote path', () => {
     expect(
       persistedProjectExecutionSpaceSchema.parse({
         kind: 'ssh',
         hostId: '00000000-0000-4000-8000-000000000301',
-        remoteRootPath: '/srv/goodbuddy',
-        validation
+        remoteRootPath: '/srv/goodbuddy'
       })
     ).toEqual({
       kind: 'ssh',
       hostId: '00000000-0000-4000-8000-000000000301',
-      remoteRootPath: '/srv/goodbuddy',
-      validation
+      remoteRootPath: '/srv/goodbuddy'
     })
-    expect(
-      sshExecutionValidationSchema.safeParse({
-        hostRevision: 2,
-        hostKeyGeneration: 3,
-        remoteUsername: 'builder',
-        workspaceIdentity: 'workspace-identity',
-        agentProtocolMajor: 1,
-        agentInstallationIdAtValidation: 'agent-installation',
-        agentBinaryDigestAtValidation: `sha256:${'a'.repeat(64)}`,
-        agentVersionAtValidation: '0.11.0',
-        agentArchitectureAtValidation: 'x64',
-        validatedAt,
-        runtimeBundleDigest: 'must-not-be-here'
-      }).success
-    ).toBe(false)
-    expect(
-      persistedProjectExecutionSpaceSchema.safeParse({
-        kind: 'local',
-        rootPath: 'C:\\Workspace',
-        validation
-      }).success
-    ).toBe(false)
     expect(
       persistedProjectExecutionSpaceSchema.safeParse({
         kind: 'ssh',
         hostId: '00000000-0000-4000-8000-000000000301',
         remoteRootPath: '/srv/goodbuddy',
-        hostRevision: 2
+        validation: { hostRevision: 2 }
       }).success
     ).toBe(false)
-
-    for (const invalid of [
-      { ...validation, hostRevision: 0 },
-      { ...validation, trustAttestationRevision: 4 },
-      {
-        ...validation,
-        agentBinaryDigestAtValidation: `sha256:${'A'.repeat(64)}`
-      },
-      { ...validation, agentVersionAtValidation: ' version ' },
-      { ...validation, agentArchitectureAtValidation: 'ia32' }
-    ]) {
-      expect(
-        sshExecutionValidationSchema.safeParse(invalid).success
-      ).toBe(false)
-    }
-
-    for (const invalid of [
-      {
-        ...runtimeValidation,
-        runtimeBundleDigest: 'runtime-digest'
-      },
-      { ...runtimeValidation, trustTier: 'T3' },
-      {
-        ...runtimeValidation,
-        confinementPolicyDigest: `sha256:${'d'.repeat(64)}`
-      },
-      { ...runtimeValidation, approvalBridgeVersion: '1' },
-      {
-        ...runtimeValidation,
-        workMode: 'plan'
-      }
-    ]) {
-      expect(
-        projectRuntimeValidationSchema.safeParse(invalid).success
-      ).toBe(false)
-    }
-    expect(
-      projectRuntimeValidationSchema.safeParse({
-        ...runtimeValidation,
-        workMode: 'ask'
-      }).success
-    ).toBe(true)
   })
 
   it('keeps renderer project create and update inputs local-only', () => {

src/shared/assistant-contracts.ts

@@ -1,6 +1,4 @@
 import { z } from 'zod'
-import { agentArchitectureSchema } from './agent-installation-contracts'
-import { sha256DigestSchema } from './agent-protocol/contracts'
 import { agentRuntimeSelectionSchema } from './runtime-selection-contracts'
 import { sshHostIdSchema } from './ssh-host-contracts'
 
@@ -32,11 +30,6 @@ export type ProjectKind = z.infer<typeof projectKindSchema>
 export type ProjectChannel = z.infer<typeof projectChannelSchema>
 
 const projectExecutionSpacePathSchema = z.string().max(4_096)
-const projectExecutionValidationTextSchema = z
-  .string()
-  .min(1)
-  .max(1_000)
-  .refine((value) => value.trim().length > 0)
 
 export const projectExecutionSpaceSchema = z.discriminatedUnion(
   'kind',
@@ -60,52 +53,8 @@ export const projectExecutionSpaceSchema = z.discriminatedUnion(
   ]
 )
 
-export const sshExecutionValidationSchema = z
-  .object({
-    hostRevision: z.number().int().positive(),
-    hostKeyGeneration: z.number().int().positive(),
-    remoteUsername: projectExecutionValidationTextSchema,
-    workspaceIdentity: projectExecutionValidationTextSchema,
-    agentProtocolMajor: z.number().int().positive(),
-    agentInstallationIdAtValidation:
-      projectExecutionValidationTextSchema,
-    agentBinaryDigestAtValidation: sha256DigestSchema,
-    agentVersionAtValidation: z
-      .string()
-      .regex(/^[0-9A-Za-z][0-9A-Za-z.+_-]{0,127}$/u),
-    agentArchitectureAtValidation: agentArchitectureSchema,
-    validatedAt: z.string().datetime({ offset: true })
-  })
-  .strict()
-
-export const projectRuntimeValidationSchema = z
-  .object({
-    runtimeSelectionKey: z.string().trim().min(1).max(1_000),
-    runtimeBundleDigest: sha256DigestSchema,
-    runtimeAdapterDigest: sha256DigestSchema,
-    agentInstallationIdAtValidation:
-      projectExecutionValidationTextSchema,
-    validatedAt: z.string().datetime({ offset: true }),
-    workMode: workModeSchema
-  })
-  .strict()
-
-export type SshExecutionValidation = z.output<
-  typeof sshExecutionValidationSchema
->
-export type ProjectRuntimeValidation = z.output<
-  typeof projectRuntimeValidationSchema
->
-
 export const persistedProjectExecutionSpaceSchema =
-  z.discriminatedUnion('kind', [
-    projectExecutionSpaceSchema.options[0],
-    projectExecutionSpaceSchema.options[1]
-      .extend({
-        validation: sshExecutionValidationSchema.optional()
-      })
-      .strict()
-  ])
+  projectExecutionSpaceSchema
 
 export type ProjectExecutionSpace = z.output<
   typeof persistedProjectExecutionSpaceSchema
@@ -513,7 +462,6 @@ export type AssistantProject = ProjectCreateInput & {
   id: string
   kind: ProjectKind
   executionSpace: ProjectExecutionSpace
-  runtimeValidation?: ProjectRuntimeValidation
   channel?: ProjectChannel
   readonly builtInDefault?: boolean
   status: 'active' | 'archived'

src/shared/contracts.ts

@@ -173,7 +173,9 @@ import type {
   SshHostDraftInspectionRequest,
   SshHostKeyInspection,
   RemoteEnvironmentUpdateProgress,
+  RemoteEnvironmentUpdateRequest,
   SshHostRemoteEnvironment,
+  SshHostRemovalResult,
   SshHostsSnapshot,
   SshDirectoryBrowseResult,
   SshHostValidationRequest,
@@ -1580,7 +1582,7 @@ export type DesktopApi = {
     onAgentPackageProgress: (
       listener: (progress: AgentPackageDownloadProgress) => void
     ) => () => void
-    remove: (hostId: string) => Promise<void>
+    remove: (hostId: string) => Promise<SshHostRemovalResult>
     inspectDraftHostKey: (
       input: SshHostDraftInspectionRequest
     ) => Promise<SshHostKeyInspection>
@@ -1591,7 +1593,9 @@ export type DesktopApi = {
     getRemoteEnvironment: (
       hostId: string
     ) => Promise<SshHostRemoteEnvironment>
-    updateRemoteEnvironment: (hostId: string) => Promise<void>
+    updateRemoteEnvironment: (
+      input: RemoteEnvironmentUpdateRequest
+    ) => Promise<void>
     cancelRemoteEnvironmentUpdate: (hostId: string) => Promise<void>
     onRemoteEnvironmentUpdateProgress: (
       listener: (progress: RemoteEnvironmentUpdateProgress) => void
@@ -1735,7 +1739,6 @@ export type DesktopApi = {
     setArchived: (projectId: string, archived: boolean) => Promise<void>
     delete: (projectId: string, confirmation: string) => Promise<void>
     remote: {
-      activate: (projectId: string) => Promise<AssistantProject>
       save: (
         input: RemoteProjectSaveRequest
       ) => Promise<AssistantProject>

src/shared/ipc-channels.ts

@@ -129,7 +129,6 @@ export const ipcChannels = {
   projectsUpdate: 'projects:update',
   projectsSetArchived: 'projects:set-archived',
   projectsDelete: 'projects:delete',
-  remoteProjectActivate: 'projects:remote:activate',
   remoteProjectSave: 'projects:remote:save',
   remoteProjectCancelCurrent: 'projects:remote:cancel-current',
   remoteProjectSaveProgress: 'projects:remote:save-progress',

src/shared/ssh-host-contracts.test.ts

@@ -7,6 +7,7 @@ import {
   sshHostCreateInputSchema,
   sshHostDraftInspectionRequestSchema,
   remoteEnvironmentUpdateProgressSchema,
+  remoteEnvironmentUpdateRequestSchema,
   sshHostRemoteEnvironmentSchema,
   sshHostValidationRequestSchema
 } from './ssh-host-contracts'
@@ -233,7 +234,12 @@ describe('SSH host contracts', () => {
           version: '1.18.9',
           architecture: 'x64'
         }
-      }]
+      }],
+      remoteDownload: {
+        available: true,
+        source: 'mirror',
+        packageSize: 1024
+      }
     }
     expect(sshHostRemoteEnvironmentSchema.parse(status)).toEqual(status)
     expect(() =>
@@ -242,23 +248,86 @@ describe('SSH host contracts', () => {
         credential: 'secret'
       })
     ).toThrow()
+    expect(() =>
+      sshHostRemoteEnvironmentSchema.parse({
+        ...status,
+        remoteDownload: {
+          available: false,
+          source: 'mirror',
+          packageSize: 1024,
+          reason: 'arbitrary-reason'
+        }
+      })
+    ).toThrow()
   })
 
-  it('strictly validates coarse remote environment update progress', () => {
+  it('strictly validates manual remote environment preparation', () => {
     const hostId = '00000000-0000-4000-8000-000000000101'
-    for (const phase of ['agent', 'runtime', 'finalizing']) {
+    for (const method of [
+      'auto',
+      'remote-download',
+      'goodbuddy-transfer'
+    ]) {
+      expect(
+        remoteEnvironmentUpdateRequestSchema.parse({
+          hostId,
+          method
+        })
+      ).toEqual({ hostId, method })
+    }
+    for (const phase of [
+      'probing',
+      'downloading',
+      'verifying',
+      'installing-agent',
+      'installing-runtime',
+      'checking-health',
+      'finalizing',
+      'complete'
+    ]) {
       expect(
         remoteEnvironmentUpdateProgressSchema.parse({
           hostId,
+          method: 'remote-download',
           phase
         })
-      ).toEqual({ hostId, phase })
+      ).toEqual({
+        hostId,
+        method: 'remote-download',
+        phase
+      })
     }
     for (const progress of [
-      { hostId: 'not-a-uuid', phase: 'agent' },
-      { hostId, phase: 'uploading' },
-      { hostId, phase: 'runtime', path: '/home/user' },
-      { hostId, phase: 'agent', command: 'whoami' }
+      {
+        hostId: 'not-a-uuid',
+        method: 'remote-download',
+        phase: 'probing'
+      },
+      { hostId, method: 'automatic', phase: 'probing' },
+      {
+        hostId,
+        method: 'remote-download',
+        phase: 'uploading'
+      },
+      {
+        hostId,
+        method: 'goodbuddy-transfer',
+        phase: 'verifying',
+        path: '/home/user'
+      },
+      {
+        hostId,
+        method: 'remote-download',
+        phase: 'downloading',
+        command: 'whoami'
+      },
+      {
+        hostId,
+        method: 'remote-download',
+        phase: 'downloading',
+        completedBytes: 2,
+        totalBytes: 1
+      }
     ]) {
       expect(() =>
         remoteEnvironmentUpdateProgressSchema.parse(progress)

src/shared/ssh-host-contracts.ts

@@ -206,6 +206,17 @@ export type SshHost = {
 export type SshHostsSnapshot = {
   hosts: SshHost[]
   secureStorageAvailable: boolean
+  projectReferences?: Record<string, SshHostProjectReference[]>
+}
+
+export type SshHostProjectReference = {
+  id: string
+  name: string
+}
+
+export type SshHostRemovalResult = {
+  hostId: string
+  deletedProjects: SshHostProjectReference[]
 }
 
 export type SshHostKeyInspection = {
@@ -249,6 +260,16 @@ export const sshHostRemoteEnvironmentStateSchema = z.enum([
   'not-installed'
 ])
 
+export const remoteEnvironmentDownloadUnavailableReasonSchema =
+  z.enum([
+    'package-unavailable',
+    'missing-tools',
+    'home-unwritable',
+    'insufficient-disk-space',
+    'source-unreachable',
+    'probe-failed'
+  ])
+
 export const sshHostRemoteEnvironmentSchema = z
   .object({
     hostId: sshHostIdSchema,
@@ -274,7 +295,31 @@ export const sshHostRemoteEnvironmentSchema = z
           })
           .strict()
       )
-      .max(16)
+      .max(16),
+    remoteDownload: z
+      .discriminatedUnion('available', [
+        z
+          .object({
+            available: z.literal(true),
+            source: z.enum(['github', 'mirror']),
+            packageSize: z.number().int().positive().safe()
+          })
+          .strict(),
+        z
+          .object({
+            available: z.literal(false),
+            source: z.enum(['github', 'mirror']).nullable(),
+            packageSize: z
+              .number()
+              .int()
+              .positive()
+              .safe()
+              .nullable(),
+            reason:
+              remoteEnvironmentDownloadUnavailableReasonSchema
+          })
+          .strict()
+      ])
   })
   .strict()
 
@@ -282,10 +327,37 @@ export type SshHostRemoteEnvironment = z.infer<
   typeof sshHostRemoteEnvironmentSchema
 >
 
+export const remoteEnvironmentPreparationMethodSchema = z.enum([
+  'auto',
+  'remote-download',
+  'goodbuddy-transfer'
+])
+
+export type RemoteEnvironmentPreparationMethod = z.infer<
+  typeof remoteEnvironmentPreparationMethodSchema
+>
+
+export const remoteEnvironmentUpdateRequestSchema = z
+  .object({
+    hostId: sshHostIdSchema,
+    method: remoteEnvironmentPreparationMethodSchema
+  })
+  .strict()
+
+export type RemoteEnvironmentUpdateRequest = z.infer<
+  typeof remoteEnvironmentUpdateRequestSchema
+>
+
 export const remoteEnvironmentUpdatePhaseSchema = z.enum([
-  'agent',
-  'runtime',
-  'finalizing'
+  'probing',
+  'downloading',
+  'verifying',
+  'applying',
+  'installing-agent',
+  'installing-runtime',
+  'checking-health',
+  'finalizing',
+  'complete'
 ])
 
 export type RemoteEnvironmentUpdatePhase = z.infer<
@@ -295,6 +367,7 @@ export type RemoteEnvironmentUpdatePhase = z.infer<
 export const remoteEnvironmentUpdateProgressSchema = z
   .object({
     hostId: sshHostIdSchema,
+    method: remoteEnvironmentPreparationMethodSchema,
     phase: remoteEnvironmentUpdatePhaseSchema
   })
   .strict()